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Preface 


This manual provides users of the OpenVMS operating system with detailed 
usage and reference information on general purpose routines supplied in the 
OTS$ facility of the Run-Time Library. 


Intended Audience 


This manual is intended for system and appt on programmers who want to 
call Run-Time Library routines. 


Document Structure 
This manual is organized into two parts as follows: 
e Part I contains a brief overview of the OTS$ routines in Chapter 1. 


¢ Part II, the OTS$ Reference Section, provides detailed reference information 
on each routine contained in the OTS$ facility of the Run-Time Library. 
This information is presented using the documentation format described 
in OpenVMS Programming Interfaces: Calling a System Routine. Routine 
descriptions appear in alphabetical order by routine name. 


Associated Documents 


The Run-Time Library routines are documented in a series of reference manuals. 
A description of how the Run-Time Library routines are accessed is presented in 
OpenVMS Programming Interfaces: Calling a System Routine. A description of 
VMS features and functionality available through calls to the OTS$ Run-Time 
Library appears in the OpenVMS Programming Concepts Manual. Descriptions 
of other RTL facilities and their corresponding routines and usages are discussed 
in the following books: 


¢ DPML, Digital Portable Mathematics Library 

¢ OpenVMS RTL DECtalk (DTK$) Manual 

¢ OpenVMS RTL Library (LIB$) Manual 

¢ OpenVMS VAX RTL Mathematics (MTH$) Manual 

¢ OpenVMS RTL Parallel Processing (PPL$) Manual 

¢ OpenVMS RTL Screen Management (SMG$) Manual 
e OpenVMS RTL String Manipulation (STR$) Manual 


The Guide to DECthreads contains guidelines and reference information for 
DECthreads, the Digital Multithreading Run-Time Library. 


Application programmers using any programming language can refer to the Guide 
to Creating OpenVMS Modular Procedures for writing modular and reentrant 
code. 


High-level language programmers will find additional information on calling 
Run-Time Library routines in their language reference manual. Additional 
information may also be found in the language user’s guide provided with your 
VMS language software. 


For a complete list and description of the manuals in the VMS documentation set, 
see the Overview of OpenVMS Documentation. 


Conventions 


vi 


In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating 
system, every use of OpenVMS VAX means the OpenVMS VAX operating system, 
and every use of OpenVMS means both the OpenVMS AXP operating system and 
the OpenVMS VAX operating system. 


The following conventions are used to identify information specific to OpenVMS 
AXP or to OpenVMS VAX: 


The AXP icon denotes the beginning of information 
AXP specific to OpenVMS AXP. 





The VAX icon denotes the beginning of information 
qiy> specific to OpenVMS VAX. 


The diamond symbol denotes the end of a section of 
4 information specific to OpenVMS AXP or to OpenVMS 
VAX. 


The following conventions are used in this manual: 


Ctrl/x A sequence such as Ctrl/x indicates down the key labeled Ctrl 
while you press another key or a pointing device button. 


PF1 x A sequence such as PFI x indicates that you must first press 
and release the key labeled PF1, then press and release 
another key or a pointing device button. 


GOLD x A sequence such as GOLD x indicates that you must first press 
and release the key defined GOLD, then press and release 
another key. GOLD key sequences can also have a slash (/), 
dash (-), or underscore (_) as a delimiter in EVE commands. 


In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


A horizontal ellipsis in examples indicates one of the following 
possibilities: 


¢ Additional optional arguments in a statement have been 
omitted. 


e The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can be 
entered. 


A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 


() 


{} 


boldface text 


italic text 


UPPERCASE TEXT 


numbers 


In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices 
in parentheses. 


In format descriptions, brackets indicate optional elements. 
You can choose one, none, or all of the options. (Brackets are 
not optional, however, in the syntax of a directory name in 
an OpenVMS file specification, or in the syntax of a substring 
specification in an assignment statement.) 


In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 


Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 


Boldface text is also used to show user input in Bookreader 
versions of the manual. 


Italic text emphasizes important information, indicates 
variables, and indicates complete titles of manuals. Italic 
text also represents information that can vary in system 
messages (for example, Internal error number), command lines 
(for example, /PRODUCER=name), and command parameters 
in text. 


Uppercase text indicates a command, the name of a routine, 
the name of a file, the name of a file protection code, or the 
abbreviation for a system privilege. 


A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 


All numbers in text are assumed to be decimal, unless 
otherwise noted. Nondecimal radixes—binary, oc 
hexadecimal—are explicitly indicated. 


Other conventions used in the documentation of Run-Time Library routines are 
described in OpenVMS Programming Interfaces: Calling a System Routine. 


vil 


7 


Overview of the OTS$ Facility 


This manual discusses the Run-Time Library OTS$ routines that perform general 
purpose functions. These functions include data type conversions as part of a 
compiler’s generated code, and some mathematical functions. 


Most of the OTS$ routines were originally designed to support language 
compilers. Because they provide useful functions, they were moved into the 
language-independent facility, OTS$. 


The OTS$ facility provides you with routines that perform seven main tasks: 


Convert data types 

Divide complex and packed decimal values 
Move data to a specified destination address 
Multiply complex values 

Raise a base to an exponent 

Copy a source string to a destination string 


Return a string area to free storage 


Table 1—1, Table 1-2, Table 1-3, Table 1-4, Table 1-5, Table 1-6, and Table 1—7 
contain all of the OTS$ routines grouped according to their functions. 


Table 1-1 OTS$ Conversion Routines 


Conversion Routine Function 
OTS$CNVOUT Convert a D-floating, G-floating, or H-floating value to a 
character string 
OTS$CVT_L_TB Convert an unsigned integer to binary text 
OTS$CVT_L_TI Convert a signed integer to signed integer text 
OTS$CVT_L_TL Convert an integer to logical text 
OTS$CVT_L_TO Convert an unsigned integer to octal text 
OTS$CVT_L_TU Convert an unsigned integer to decimal text 
OTS$CVT_L_TZ Convert an integer to hexadecimal text 
OTS$CVT_TB_L Convert binary text to an unsigned integer value 
OTS$CVT_TI_L Convert signed integer text to an integer value 
OTS$CVT_TL_L Convert logical text to an integer value 


OTS$CVT_TO_L Convert octal text to an integer value 


(continued on next page) 


Overview of the OTS$ Facility 


Table 1-1 (Cont.) OTS$ Conversion Routines 


Conversion Routine Function 

OTS$CVT_TU_L Convert unsigned decimal text to an integer value 

OTS$CVT_T_z Convert numeric text to a D- or F-floating value 

OTS$CVT_T_x Convert numeric text to a G- or H-floating value 

OTS$CVT_TZ_L Convert hexadecimal text to an unsigned longword integer 
- value 


For more information on Run-Time Library conversion routines, see the CVT$ 
reference section in the OpenVMS RTL Library (LIB$) Manual. | 


Table 1-2 OTS$ Division Routines 


Division Routine Function 

OTS$DIVCx Perform complex division 

OTS$DIV_PK_LONG Perform packed decimal division with a long 
divisor 

OTS$DIV_PK_SHORT Perform packed decimal division with a short 
divisor 


Table 1-3 OTS$ Move Data Routines 


Move Data Routine Function 
OTS$MOVE3 Move data without fill 
OTS$MOVE5 Move data with fill 


Table 1-4 OTS$ Multiplication Routine 
Multiplication Routine | Function 


OTS$MULCx Perform complex multiplication 


Table 1-5 OTS$ Exponentiation Routines 


Exponentiation Routine Function | 

OTS$POWCxCx Raise a complex base to a complex floating- 
point exponent 

OTS$POWCxJ Raise a complex base to a signed longword 

. exponent 

OTS$POWDD Raise a D-floating base to a D-floating 
exponent 

OTS$POWDR Raise a D-floating base to an F-floating 
exponent 

OTS$POWDJ Raise a D-floating base to a longword integer 
exponent 


- (continued on next page) 
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Table 1-5 (Cont.) OTS$ Exponentiation Routines 


Exponentiation Routine 


OTS$POWGx 
OTS$POWGJ 
+OTS$POWHx 
OTS$POWHJ 
OTS$POWII 
OTS$POWHJIJ 
OTS$POWLULU 
OTS$POWxLU 
OTS$POWRD 
OTS$POWRJ 


OTS$POWRR 


*VAX VMS specific. 


Function 


Raise a G-floating base to a G-floating or 
longword integer exponent 


Raise a G-floating base to a longword integer 
exponent 


Raise an H-floating base to a floating-point 
exponent 


Raise an H-floating base to a longword integer 
exponent 


Raise a word integer base to a word integer 
exponent 


Raise a longword integer base to a longword 
integer exponent 


Raise an unsigned longword integer base to an 
unsigned longword integer exponent 


Raise a floating-point base to an unsigned 
longword integer exponent 


Raise an F-floating base to a D-floating 
exponent 


Raise an F-floating base to a longword integer 
exponent 


Raise an F-floating base to an F-floating 
exponent 


Table 1-6 OTS$ Copy Source String Routines 


Copy Source String Routine 
OTS$SCOPY_DXDX 


OTS$SCOPY_R_DX 


Function 


Copy a source string passed by descriptor to a 
destination string 


Copy a source string passed by reference to a 
destination string 


Table 1-7 OTS$ Return String Area Routines 


Return String Area Routine 


OTS$SFREE1_DD 
OTS$SFREEN_DD 


OTS$SGET1_DD 


Function 


Free one dynamic string 
Free n dynamic strings 


Get one dynamic string 


OTSS Reference Section 


This section provides detailed descriptions of the routines provided by the VMS 
RTL General Purpose (OTS$) Facility. 


OTS$CNVOUT 


OTS$SCNVOUT—Convert D-Floating, G-Floating or H-Floating 


Format 


<i> 


Returns 


Arguments 


Number to Character String 


The Convert Floating to Character String routines convert a D-floating, G-floating 
or H-floating number to a character string in the FORTRAN E format. 


OTS$CNVOUT D-G-or-H-float-pt-input-val_,fixed-length-resultant-string 
,digits-in-fraction 


OTS$CNVOUT_G_ D-G-or-H-float-pt-input-val ,fixed-length-resultant-string 
,digits-in-fraction 


OTS$CNVOUT_HD-G-or-H-float-pt-input-val_ ,fixed-length-resultant-string 
,digits-in-fraction 


OpenVMS usage cond_value © 


type longword (unsigned) 
access write only 
mechanism by value 


D-G-or-H-float-pt-input-val 
OpenVMS usage _ floating_point 


type D_floating, G_floating, H_floating 
access read only 
mechanism by reference 


Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT, 
the D-G-or-H-float-pt-input-val argument is the address of a D-floating number 
containing the value. For OTS$CNVOUT_G, the D-G-or-H-float-pt-input- 

val argument is the address of a G-floating number containing the value. For 
OTS$CNVOUT_H, the D-G-or-H-float-pt-input-val argument is the address of 
an H-floating number containing the value. 


fixed-length-resultant-string 
OpenVMS usage _  char_string 


type character string 
access write only 
mechanism by descriptor, fixed length 


Output string into which OTS$CNVOUT writes the character string result of the 
conversion. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to the output string. 


COATC_a 


OTS$CNVOUT 


digits-in-fraction 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
mechanism by value 


Number of digits in the fractional portion of the result. The digits-in-fraction 
argument is an unsigned longword containing the number of digits to be written 
to the fractional portion of the result. 


Condition Values Returned 


OTS—A 


SS$_NORMAL Normal successful completion. 
SS$ ROPRAND Floating reserved operand detected. 
OTS$_OUTCONERR Output conversion error. The result would have 


exceeded the fixed-length string; the output 
string is filled with asterisks. 


OTS$CVT_L_TB 


OTS$CVT_L_TB—Convert an Unsigned Integer to Binary Text 


Format 


Returns 


Arguments 


The Convert an Unsigned Integer to Binary Text routine converts an unsigned 
integer value of arbitrary length to binary representation in an ASCII text string. 
By default, a longword is converted. 


OTS$CVT_L_TB_ varying-input-value _,fixed-length-resultant-string [,;number-of-digits] 
[input-value-size] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


varying-input-value 
OpenVMS usage varying_arg 


type unspecified 
access read only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_L_TB converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 
OpenVMS usage _char_string 


type character string 
access write only 
mechanism by descriptor, fixed-length 


ASCII text string that OTS$CVT_L_TB creates when it converts the integer 
value. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to this ASCII text string. The string is assumed to be of 
fixed length (DSC$K_CLASS_S). 


number-of-digits 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Minimum number of digits in the binary representation to be generated. The 
number-of-digits argument is a signed longword containing this minimum 
number. If the minimum number of digits is omitted, the default is 1. If the 
actual number of significant digits is less than the minimum number of digits, 
leading zeros are produced. If the minimum number of digits is zero and the 
value of the integer to be converted is also zero, OTS$CVT_L_TB creates a blank 
string. 


OTCO_A 


OTS$CVT_L_TB 


input-value-size 
OpenVMS usage longword_signed 


type longword (signed) 

access read only 

mechanism by value 

Size of the integer to be converted, in bytes. The input-value-size argument is 


a signed longword containing the byte size. This is an optional argument. If the 


size 


is omitted, the default is 4 (longword). 


Condition Values Returned 


Example 


OTS-6 


SS$_NORMAL Normal successful completion. 
OTS$ OUTCONERR Output conversion error. The result would have 


1234 


exceeded the fixed-length string; the output 
string is filled with asterisks. 


0 | if | 2 | 3 | 4 | 5 | 6 | q | 


5678901234567890123456789012345678901234567890123456789012345678901234567890 
ETTY D F 4 Tay 

C* Initialize numeric value to be converted. 

iG Z-ADD13 VALUE 90 

C CVTLTB EXTRN’OTSSCVT_L_ TB’ 

C* Convert the number to binary in a string. 

C CALL CVTLTB 

c PARM VALUE RL 
C PARMD OUTSTR 4 

C* Display the converted string on the terminal. 

C OUTSTR DSPLYTTY 

G SETON LR 


This RPG II program displays the string ‘1101’ on the terminal. 


OTSSCVT_L_TI 


OTS$CVT_L_Ti—Convert Signed Integer to Decimal Text 


Format 


Returns 


Arguments 


The Convert Signed Integer to Decimal Text routine converts a signed integer to a 
decimal ASCII text string: This routine supports FORTRAN Iw and Iw.m output 
and BASIC output conversion. 


OTS$CVT_L_TI varying-input-value _,fixed-length-resultant-string [,;number-of-digits] 
Linput-value-size] [,flags-value] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


varying-input-value 
OpenVMS usage varying_arg 


type unspecified 
access read only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_L_TI converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor, fixed length 


Decimal ASCII text string that OTS$CVT_L_TI creates when it converts the 
signed integer. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to this text string. The string is assumed to be of fixed length 
(DSC$K_CLASS_S). 


number-of-digits 
OpenVMS usage longword_signed 


type | longword (signed) 
access read only 
mechanism by value 


Minimum number of digits to be generated when OTS$CVT_L_TI converts the 
signed integer to a decimal ASCII text string. The number-of-digits argument 
is a signed longword containing this number. If the minimum number of digits 
is omitted, the default value is 1. If the actual number of significant digits is 
smaller, OTS$CVT_L_TI inserts leading zeros into the output string. If number- 
of-digits is zero and varying-input-value is zero, OTS$CVT_L_TI writes a 
blank string to the output string. 


OTS-7 


OTSS$CVT_L_TI 


input-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Size of the integer to be converted, in bytes. The input-value-size argument is 
a signed longword containing this value size. The value size must be either 1, 
2, or 4. If value size is 1 or 2, the value is sign-extended to a longword before 
conversion. If the size is omitted, the default is 4 (longword). 


flags-value 

OpenVMS usage mask_longword | 
type longword (unsigned) 
access read only 
mechanism by value 


Caller-supplied flags that you can use if you want OTS$CVT_L_TI to insert a 
plus sign before the converted number. The flags-value argument is an unsigned 
longword containing the flags. 


The caller flags are defined as follows: 


Bit 0 If set, a plus sign (+) is inserted before the first nonblank character in 
the output string; otherwise, the plus sign is omitted. 


If flags-value is omitted, all bits are clear and the plus sign is not inserted. 


Condition Values Returned 


OTS-8 


SS$_NORMAL Normal successful completion. 


OTS$_OUTCONERR Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


OTS$CVT_L_TL 


OTS$CVT_L_TL—Convert Integer to Logical Text 


Format 


Returns 


Arguments 


The Convert Integer to Logical Text routine converts an integer to an ASCII text 
string representation using FORTRAN L (logical) format. 


OTS$CVT_L_TL longword-integer-value ,fixed-length-resultant-string 


OpenVMS usage _ cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


longword-integer-value 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by reference 


Value that OTS$CVT_L_TL converts to an ASCII text string. The longword- 
integer-value argument is the address of a signed longword containing this 
integer value. 


fixed-length-resultant-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor, fixed length 


Output string that OTS$CVT_L_TL creates when it converts the integer value 
to an ASCII text string. The fixed-length-resultant-string argument is the 
address of a descriptor pointing to this ASCII text string. 


The output string is assumed to be of fixed length (DSC$K_CLASS_S). 


If length equals the fixed length of the output string, then the output string 
consists of (length — 1) blanks followed by the letter T if bit 0 is set, or the letter 
F if bit 0 is clear. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


OTS$_OUTCONERR Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is of zero length (DSC$W_LENGTHE 0). 
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Example 


5 I+ 
! This 1s an example program 
! showing the use of OTSSCVT_L_TL. 


VALUES = 10 
OUTSTRS =: 2° * 
CALL OTSSCVT_L_TL(VALUE%, OUTSTRS) 


PRINT OUTSTRS 
9 END 


This BASIC example illustrates the use of OTS$CVT_L_TL. The output generated 
by this program is 'F’. 


OTS-10 


OTS$CVT_L_TO 


OTS$CVT_L_TO—Convert Unsigned Integer to Octal Text 


Format 


Returns 


Arguments 


The Convert Unsigned Integer to Octal Text routine converts an unsigned integer 
to an octal ASCII text string. OTS$CVT_L_TO supports FORTRAN Ow and 
Ow.m output conversion formats. 


OTS$CVT_L_TO  varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


OpenVMS usage _ cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


varying-input-value 
OpenVMS usage varying_arg 


type unspecified 
access read only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_L_TO converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor, fixed length 


Output string that OTS$CVT_L_TO creates when it converts the integer value 
to an octal ASCII text string. The fixed-length-resultant-string argument is 
the address of a descriptor pointing to the octal ASCII text string. The string is 
assumed to be of fixed length (DSC$K_CLASS_S). 


number-of-digits 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Minimum number of digits that OTS$CVT_L_TO generates when it converts the 
integer value to an octal ASCII text string. The number-of-digits argument 

is a signed longword containing the minimum number of digits. If it is omitted, 
the default is 1. If the actual number of significant digits in the octal ASCII 
text string is less than the minimum number of digits, OTS$CVT_L_TO inserts 
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leading zeros into the output string. If number-of-digits is zero and varying- 
input-value is zero, OTS$CVT_L_TO writes a blank string to the output 
string. 


input-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Size of the integer to be converted, in bytes. The input-value-size argument is a 
signed longword containing the number of bytes in the integer to be converted by 
OTS$CVT_L_TO. If it is omitted, the default is 4 (longword). 


Condition Values Returned 
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SS$_NORMAL Normal successful completion. 


OTS$_OUTCONERR Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


OTS$CVT_L_TU 


OTS$CVT_L_TU—Convert Unsigned Integer to Decimal Text 


Format 


Returns 


Arguments 


The Convert Unsigned Integer to Decimal Text routine converts a byte, word, or 
longword value to unsigned decimal representation in an ASCII text string. By 
default, a longword is converted. 


OTS$CVT_L_TU  varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[ ,Input-value-size] 


| OpenVMS usage _ cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


varying-input-value 
OpenVMS usage varying_arg 


type unspecified 
access read only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_L_TU converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor, fixed-length 


Output string (fixed-length) that OTS$CVT_L_TU creates when it converts the 
integer value to unsigned decimal representation in an ASCII text string. The 
fixed-length-resultant-string argument is the address of a descriptor pointing 
to this ASCII text string. 


number-of-digits 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Minimum number of digits in the ASCII text string that OTS$CVT_L_TU creates. — 
The number-of-digits argument is a signed longword containing the minimum 
number. If the minimum number of digits is omitted, the default is 1. 
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If the actual number of significant digits in the output string created is less than 
the minimum number, OTS$CVT_L_TU inserts leading zeros into the output 
string. If the minimum number of digits is zero and the integer value to be 
converted is also zero, OTS$CVT_L_TU writes a blank string to the output string. 


input-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Size of the integer value to be converted, in bytes. The input-value-size 
argument is a signed longword containing the size of the integer value. If the size 
is omitted, the default is 4. The only values that OTS$CVT_L_TU allows are 1, 

2 and 4. If any other value is specified, OTS$CVT_L_TU uses the default value, 
which is 4 (longword). 


Condition Values Returned 


Example 
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SS$_NORMAL Normal successful completion. 


OTS$_ OUTCONERR Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


0 il | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 

FTTY D F 7 TLY. 

C* Initialize numeric value to be converted. 

C Z~-ADD32857 VALUE 90 

C Z-ADD7 DIGITS 90 

C CVTLTU EXTRN’ OTSSCVT_L_TU’ 

C* Convert the number to decimal in a string with 7 decimal digits. 

e CALL CVTLTU 

C PARM VALUE RL 

C PARMD OUTSTR 7 

es PARMV DIGITS 

C* Display the converted string on the terminal. 

C OUTSTR DSPLYTTY 

€ SETON LR 


This RPG II program displays the string ‘0032857’ on the terminal screen. 


OTS$CVT_L_TZ 


OTSS$CVT_L_TZ—Convert Integer to Hexadecimal Text 


Format 


Returns 


Arguments 


The Convert Integer to Hexadecimal Text routine converts an unsigned integer to 
a hexadecimal ASCII text string. OTS$CVT_L_TZ supports FORTRAN Zw and 
Zw.m output conversion formats. 


OTS$CVT_L_TZ_ varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


varying-input-value 
OpenVMS usage varying_arg 


type unspecified 
access read only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor, fixed length 


Output string that OTS$CVT_L_TZ creates when it converts the integer value to 
a hexadecimal ASCII text string. The fixed-length-resultant-string argument 
is the address of a descriptor pointing to this ASCII text string. The string is 
assumed to be of fixed length (DSC$K_CLASS_S). 


number-of-digits 
OpenVMS usage  longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ creates 
when it converts the integer. The number-of-digits argument is a signed 
longword containing this minimum number. If it is omitted, the default is 1. If 
the actual number of significant digits in the text string that OTS$CVT_L_TZ 
creates is less than this minimum number, OTS$CVT_L_TZ inserts leading zeros 
in the output string. If the minimum number of digits is zero and the integer 
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value to be converted is also zero, OTS$CVT_L_TZ writes a blank string to the 
output string. 


input-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Size of the integer that OTS$CVT_L_TZ converts, in bytes. The input-value-size 
argument is a signed longword containing the value size. If the size is omitted, 
the default is 4 (ongword). 


Condition Values Returned 


Example 
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SS$ NORMAL Normal successful completion. 


OTS$_OUTCONERR Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


with TEXT_IO; use TEXT_IO; 
procedure SHOW_CONVERT is 


type INPUT_INT is new INTEGER range 0..INTEGER’ LAST; 


INTVALUE : INPUT_INT := 256; 
HEXSTRING : STRING(1..11); 


procedure CONVERT_TO_HEX (I : in INPUT_INT; HS : out STRING); 
pragma INTERFACE (RTL, CONVERT_TO_HEX) ; 
pragma IMPORT_routine (INTERNAL => CONVERT_TO_HEX, 
EXTERNAL => "OTSSCVT_L_TZ", 
MECHANISM =>(REFERENCE, 
DESCRIPTOR (CLASS => S))); 


begin 
CONVERT_TO_HEX (INTVALUE, HEXSTRING) ; 
PUT_LINE("This is the value of HEXSTRING"); 
PUT_LINE (HEXSTRING) ; 

end; 


This VAX Ada example uses OTS$CVT_L_TZ to convert a longword integer to 
hexadecimal text. 


OTSSCVT_TB_L 


OTS$CVT_TB_L—Convert Binary Text to Unsigned Integer 


Format 


Returns 


Arguments 


The Convert Binary Text to Unsigned Integer routine converts an ASCII text 
string representation of an unsigned binary value to an unsigned integer value of 
arbitrary length. By default, the result is a longword. Valid input characters are 
the blank and the digits 0 and 1. No sign is permitted. 


OTS$CVT_TB_L_ input-string ,varying-output-value [,output-value-size] [,flags-value] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 
input-string 

OpenVMS usage _ char_string 

type character string 
access read only 
mechanism by descriptor 


Input string containing the string representation of an unsigned binary value 
that OTS$CVT_TB_L converts to an integer value. The input-string argument 
is the address of a descriptor pointing to the string. 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
access write only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TB_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


output-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Number of bytes to be occupied by the value created when OTS$CVT_TB_L 
converts the ASCII text string to an integer value. The output-value-size 
argument contains the value size. If output-value-size contains a zero or a 
negative number, OTS$CVT_TB_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TB_L creates is a byte, 
word, or longword. If the number of bytes is omitted, the default is 4 (longword). 
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flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags that OTS$CVT_TB_L uses to determine how to interpret 
blanks and tabs. The flags-value argument contains the value of the user- 
supplied flags. 


The flags are defined as follows: 


Bit 
0 


4 


Description 
If set, OTS$CVT_TB_L ignores blanks. If clear, OTS$CVT_TB_L 
interprets blanks as zeros. , 


If set, OTS$CVT_TB_L ignores tabs. If clear, OTS$CVT_TB_L 
interprets tabs as invalid characters. 


The default is that all bits are clear. 


Condition Values Returned 


Example 
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SS$_NORMAL Normal successful completion. 
OTS$_INPCONERR Input conversion error. An invalid character, 


overflow, or invalid input-value-size occurred. 


OPTION 5 
TYPE = EXPLICIT 


! This program demonstrates the use of OTSSCVT_TB_L from BASIC. 
! Several. binary numbers are read and then converted to their 
! aiunteger equivalents. 


‘4 


o— 


DECLARATIONS 


DECLARE STRING BIN_STR 

DECLARE LONG BIN_VAL, I, RET_STATUS 

DECLARE LONG CONSTANT FLAGS = 17 1 2°0 + 2%4 

EXTERNAL LONG FUNCTION OTSSCVT_TB_L (STRING, LONG, & 
LONG BY VALUE, LONG BY VALUE) 


ee 
! MAIN PROGRAM 


= 


UE 
! Read the data, convert it to binary, and print the result. 


OTS$CVT_TB_L 


POR? de ede POS 
READ BIN_STR 
RET_STATUS = OTSSCVT_TB_L( BIN_STR, BIN_VAL, ‘'4’L, FLAGS) 
PRINT BIN_STR;" treated as a binary number equals";BIN_VAL 
NEXT I 


bee 
! Done, end the program. 


GOTO 32767 
999 Data EU gn EI MAO LIL Ma COUCU0U0s 
32767 END 


This BASIC example program demonstrates how to call OTS$CVT_TB_L to 
convert binary text to a longword integer. 


The output generated by this BASIC program is as follows: 


1111 treated as a binary number equals 15 

1 111 treated as a binary number equals 15 
1011011 treated as a binary number equals 91 
11111111 treated as a binary number equals 255 
00000000 treated as a binary number equals 0 
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OTS$CVT_TI_L—Convert Signed Integer Text to Integer 


Format 


Returns 


Arguments 
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The Convert Signed Integer Text to Integer routine converts an ASCII text string 
representation of a decimal number to a signed byte, word, or longword integer 
value. The result is a longword by default, but the calling program can specify a 
byte or a word value instead. 


OTS$CVT_TI_L _ fixed-or-dynamic-input-string ,varying-output-value 
[,output-value-size] [,flags-value] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism -_ by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string , 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input ASCII text string that OTS$CVT_TI_L converts to a signed byte, word, 
or longword. The fixed-or-dynamic-input-string argument is the address of a 
descriptor pointing to the input string. 


The syntax of a valid ASCII text input string is as follows: 
[+ or —] <integer-digits> 


OTS$CVT_TI_L always ignores leading blanks. A decimal point is assumed at 
the right of the input string. 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
ACCeSS. write only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TI_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value 1 is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


output-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Number of bytes to be occupied by the value created when OTS$CVT_TI_L 
converts the ASCII text string to an integer value. The output-value-size 


OTSS$CVT_TILL 


argument contains the number of bytes. If output-value-size contains a zero or 
a negative number, OTS$CVT_TI_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TI_L creates is a byte, word, 
or longword. If the number of bytes is omitted, the default is 4 (longword). 


flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and tabs 
are interpreted. The flags-value argument is an unsigned longword containing 
the value of the flags. 


Bit Description 
0 If set, OTS$CVT_TI_L ignores all blanks. If clear, OTS$CVT_TI_ 


L ignores leading blanks but interprets blanks after the first legal 
character as zeros. 


4 If set, OTS$CVT_TI_L ignores tabs. If clear, OTS$CVT_TI_L interprets 
tabs as invalid characters. 


If flags-value is omitted, the default is that all bits are cleared. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


OTS$_INPCONERR Input conversion error: an invalid character in 
the input string; or the value overflows byte, 
word, or longword; or output-value-size is 
invalid. Varying-output-value is set to zero. 
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OTS$CVT_TL_L—Convert Logical Text to Integer 


Format 


Returns 


Arguments 
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The Convert Logical Text to Integer routine converts an ASCII text string 
representation of a FORTRAN-77 L format to a byte, word, or longword integer 
value. The result is a longword by default, but the calling program can specify a 
byte or a word value instead. 


OTS$CVT_TL_L  fixed-or-dynamic-input-string ,varying-output-value 
[ ,output-value-size] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input string containing an ASCII text representation of a FORTRAN-77 L format 
that OTS$CVT_TL_L converts to a byte, word, or longword integer value. The 
fixed-or-dynamic-input-string argument is the address of a descriptor pointing 
to the input string. 


The syntax of a valid ASCII text input string is either: Blank (end of string) or 
Blank Period Letter Character (end of string) 


The elements in the preceding input string are defined as follows: 


Term Description 

Blank Zero or more blanks 

Period . or nothing 

Letter T, t, F, or f 

Character Zero or more of any character 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
access write only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TL_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 
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OTS$CVT_TL_L returns —1 as the contents of the varying-output-value 
argument if the character denoted by “Letter” is “T” or “t”. Otherwise, OTS$CVT_ 
TL_L sets varying-output-value to zero. 


output-value-size 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Number of bytes to be occupied by the value created when OTS$CVT_TL_L 
converts the ASCII text string to an integer value. The output-value-size 
argument contains the number of bytes. If output-value-size contains a zero or 
a negative number, OTS$CVT_TL_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TI_L creates is a byte, word, 
or longword. If it is omitted, the default is 4 (longword). 


Condition Values Returned 


SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Invalid character in the input string or invalid 
input-value-size; varying-input-value is set 
to zero. 
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OTS$CVT_TO_L—Convert Octal Text to Signed Integer 


Format 


Returns 


Arguments 
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The Convert Octal Text to Signed Integer routine converts an ASCII text string 
representation of an octal value to a signed integer of an arbitrary length. The 
result is a longword by default, but the calling program can specify a byte, word, 
or longword. 


OTS$CVT_TO_L  fixed-or-dynamic-input-string ,varying-output-value 
[,output-value-size] [,flags-value] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input string containing an ASCII text string representation of an octal value that 
OTS$CVT_TO_L converts to a signed integer. The fixed-or-dynamic-input- 
string argument is the address of a descriptor pointing to the input string. The 
valid input characters are blanks and the digits are 0 through 7. No sign is 
permitted. | 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
access write only 
mechanism by reference 


Signed byte, word, or longword that OTS$CVT_TO_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the signed integer. 


output-value-size 
OpenVMS usage longword_signed 


type longword integer (signed) 
access read only 
mechanism by value 


Number of bytes occupied by the signed integer value. The output-value-size 
argument contains the number of bytes. If the content of the output-value-size 
argument is zero or a negative number, OTS$CVT_TO_L returns an error. If the 
number of bytes is omitted, the default is 4 (longword). 
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flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags that OTS$CVT_TO_L uses to determine how blanks within 
the input string are interpreted. The flags-value argument contains the user- 
supplied flags. 


Bit 0 If set, OTS$CVT_TO_L ignores all blanks. If clear, OTS$CVT_TO_L 
interprets blanks as zeros. 


If flags-value is omitted, the default is that all bits are clear. 


Condition Values Returned 


Example 


SS$ NORMAL Normal successful completion. 


OTS$_INPCONERR Input conversion error. An invalid character, 
overflow, or invalid input-value-size occurred. 


OCTAL_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 


SINCLUDE SSTSDEF; /* Include definition of return status values ae | 

DECLARE OTSSCVT_TO_L ENTRY 
(CHARACTER (*), /* Input string passed by descriptor a, 
FIXED BINARY (31), /* Returned value passed by reference */ 
FIXED BINARY VALUE, /* Size for returned value passed by value */ 
FIXED BINARY VALUE) /* Flags passed by value */ 
RETURNS (FIXED BINARY (31)) /* Return status ay 
OPTIONS (VARIABLE) ; /* Arguments may be omitted as 


DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 

DECLARE SIZE FIXED BINARY(31) INITIAL(4) READONLY STATIC; /* Longword x} 
DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks */ 


ON ENDFILE (SYSIN) STOP; 


DO WHILE (‘1'B); /* Loop continuously, until end of file st 
PUT SKIP (2); 
GET LIST (INPUT) OPTIONS (PROMPT (‘Octal value: ')); 
STSSVALUE = OTSSCVT_TO_L (INPUT, VALUE, SIZE, FLAGS); 
IF “STSSSUCCESS THEN RETURN (STSSVALUE) ; 
PUT SKIP EDIT (INPUT, ‘Octal equals’, VALUE, ‘Decimal’) 
(A,X,A,X,F(10) ,X,A); 
END; 


END OCTAL_CONV; 


This PL/I program translates an octal value in ASCII into a fixed binary value. 
The program is run interactively; simply press Ctrl/Z to quit. 


S RUN OCTAL 

Octal value: 1 

1 Octal equals 1 Decimal 

Octal value: 11 

11 Octal equals 9 Decimal 

Octal value: 1017346 

1017346 Octal equals 274150 Decimal 
Octal value: Ctrl/Z 
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OTS$CVT_TU_L—Convert Unsigned Decimal Text to Integer 


Format 


Returns 


Arguments 
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The Convert Unsigned Decimal Text to Integer routine converts an ASCII text 
string representation of an unsigned decimal value to an unsigned byte, word, or 
longword value. By default, the result is a longword. Valid input characters are 
the space and the digits 0 through 9. No sign is permitted. 


OTS$CVT_TU_L _ fixed-length-input-string ,varying-output-value [,output-value-size] 
[ ,flags-value] | 


OpenVMS usage _ cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-length-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length 


Input string (fixed-length) containing an ASCII text string representation of 
an unsigned decimal value that OTS$CVT_TU_L converts to a byte, word, or 
longword value. The fixed-length-input-string argument is the address of a 
descriptor pointing to the input string. 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
access write only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TU_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


output-value-size 
OpenVMS usage longword_signed 


type longword integer (signed) 
access read only 
mechanism by value 


Number of bytes occupied by the value created when OTS$CVT_TU_L converts 
the input string. The output-value-size argument contains the number of bytes. 
OTS$CVT_TU_L allows value sizes of 1, 2 and 4. If any other value is specified, 
or if output-value-size is omitted, OTS$CVT_TU_L uses the default, which is 4. 
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flags-value 

OpenVMS usage mask _longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags that OTS$CVT_TU_L uses to determine how blanks and tabs 
are interpreted. The flags-value argument contains the user-supplied flags. 


Bit Description 


0 If set, OTS$CVT_TU_L ignores blanks. If clear, OTS$CVT_TU_L 
interprets blanks as zeros. 


4 If set, OTS$CVT_TU_L ignores tabs. If clear, OTS$CVT_TU_L interprets 
' tabs as invalid characters. 


If it is omitted, the default is that all bits are clear. 


Condition Values Returned 


SS$_NORMAL Normal successful completion. 


OTS$_INPCONERR Input conversion error. An invalid character, 
overflow or invalid input-value-size occurred. 
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OTS$CVT_T_z 


OTS$CVT_T_z—Convert Numeric Text to D- or F-Floating Value 


Format 


Returns 


Arguments 
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The Convert Numeric Text to D- or F-Floating routines convert an ASCII text 
string representation of a numeric value to a D-floating or F-floating value. 


OTS$CVT_T_D _ fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] 
[,scale-factor] [,flags-value] [,extension-bits] 


OTS$CVT_T_F  fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] 
[,scale-factor] [,flags-value] [,extension-bits] 


OpenVMS usage _ cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input string containing an ASCII text string representation of a numeric value 
that OTS$CVT_T_z converts to a D-floating or F-floating value. The fixed-or- 

dynamic-input-string argument is the address of a descriptor pointing to the 
input string. | | 


The syntax of a valid input string is as follows: 
Blank Sign Digit Period Digit!etter blank sign OR sign digzt 


The elements in the preceding input string are defined as follows: 


Term Description 

Blank Zero or more blanks 

Sign +, —, or nothing 

‘Digit Zero or more decimal digits 
Period . or nothing 

Letter E, e, D, d, Q, or q 


There is no difference in semantics among any of the six valid exponent letters 
(i, e, D, d, Q, q). 


floating-point-value 
OpenVMS usage  floating_point 


type D_fioating, F_floating 
access write only 
mechanism by reference 


OTS$CVT_T_z 


Floating-point value that OTS$CVT_T_z creates when it converts the input 
string. The floating-point-value argument is the address of the floating-point 
value. For OTS$CVT_T_D, floating-point-value is a D-floating number. For 
OTS$CVT_T_F, floating-point-value is an F-floating number. 


digits-in-fraction 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
mechanism by value 


Number of digits in the fraction if no decimal point is included in the input string. 
The digits-in-fraction argument contains the number of digits. If the number of 
digits is omitted, the default is zero. 


scale-factor 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Scale factor. The scale-factor argument contains the value of the scale factor. 
If bit 6 of the flags-value argument is clear, the resultant value is divided by 
108cale—factor unless the exponent is present. If bit 6 of flags-value is set, the 
scale factor is always applied. If the scale factor is omitted, the default is zero. 


flags-value 

OpenVMS usage mask _longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags. The flags-value argument contains the user-supplied flags. 


Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T _z 
interprets blanks as zeros. 
Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If clear, 


OTS$CVT_T_z allows E, e, D, d, Q and q exponents. (Bit 1 is clear for 
BASIC and set for FORTRAN.) 


Bit 2 If set, OTS$CVT_T_z interprets an underflow as an error. If clear, 
OTS$CVT_T_z does not interpret an underflow as an error. 

Bit 3 If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_T-z 
rounds the value. 

Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets 
tabs as invalid characters. 

Bit 5 If set, an exponent must begin with a valid exponent letter. If clear, 
the exponent letter can be omitted. 

Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If clear, 


OTS$CVT_T_z applies the scale factor only if there is no exponent 
present in the string. 


If flags-value is omitted, all bits are clear. 
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Description 


extension-bits 
OpenVMS usage word_signed 


type word (signed) 
access write only 
mechanism by reference 


Extra precision bits. The extension-bits argument is the address of a word 
containing the extra precision bits. If extension-bits is present, floating-point- 
value is not rounded, and the first n bits after truncation are returned in this 
argument. | 


These values are suitable for use as the extension operand in an EMOD 
instruction. 


These routines support FORTRAN D, E, F, and G input type conversion as well 
as similar types for other languages. 


OTS$CVT_T_D and OTS$CVT_T_F provide run-time support for BASIC and 
FORTRAN input statements. 


Condition Values Returned 


Example 
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SS$_NORMAL Normal successful completion. 


OTS$_ INPCONERR Input conversion error; an invalid character in 
the input string, or the value is outside the range 
that can be represented. Floating-point-value 
is set to +0.0 (not reserved operand —0.0). 


C+ 

C This is a FORTRAN program demonstrating the use of 
COTSSCVIE TF. 

C- 


REAL*4 A 
CHARACTER*10 T(5) 
DATA T/'12345674+23','8.786534+3', '-983476E-3', '-23.734532','45'/ 
Don 2 T= 1S 
PY PE de ECL) 
1 FORMAT(’ Input string ‘',1I1,’ 1s ’',A10) 


C+ 

C B is the return status. 

C T(I) is the string to be converted to an 

C F-floating point value. A is the F-floating 

C point conversion of T(I). %@VAL(5) means 5 digits 
C are in the fraction if no decimal point is in 

C the input string T(I). 


Ce 
B = OTSSCVT_T_F(T(I),A,%VAL(5),,) 
TYPE *,’ Output of OTSCVT_T_F is re 
Tie ey 2 
2 CONTINUE 
END 


OTSSCVT T z 


This FORTRAN example demonstrates the use of OTS$CVT_T_F. The output 
generated by this program is as follows: 


Input string 1 is 1234567423 


Output of OTSCVT_T_F is 1.2345669E+24 
Input string 2 is 8.786534+3 

Output of OTSCVT_T_F is 8786.534 
Input string 3 1s -983476E-3 

Output of OTSCVT_T_F is -9.8347599E-03 
Input string 4 is -23.734532 

Output of OTSCVT_T_F is =23:13453 
Input string 5 is 45 

Output of OTSCVT_T_F is 45000.00 
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OTS$CVT_T_z—Convert Numeric Text to G- or H-Floating Value 


Format 


<i> 


Returns 


Arguments 
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The Convert Numeric Text to G- or H-Floating routines convert an ASCII text 
string representation of a numeric value to a G-floating or H-floating value. 


OTS$CVT_T_G_ fixed-or-dynamic-input-string ,floating-pointf-value [,digits-in-fraction] 
[,scale-factor] [,flags-value] [,extension-bits] 


OTSSCVT_T_H _ fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] 
[,scale-factor] [,flags-value] [,extension-bits] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input string containing an ASCII text string representation of a numeric value 
that OTS$CVT_T_z converts to a G-floating or H-floating value. The fixed-or- 
dynamic-input-string argument is the address of a descriptor pointing to the 
input string. 


The syntax of a valid input string is as follows: 
Blank Sign Digit Period Digit'etter blank sign OR sign digit 


The elements in the preceding input string are defined as follows: 


Term Description 

Blank Zero or more blanks 

Sign +, —, or nothing 

Digit Zero or more decimal digits 
Period . or nothing 

Letter E, e, D, d, Q, or g 


There is no difference in semantics among any of the six valid exponent letters 
(Ei, e, D, d, Q, q). 


floating-point-value 
OpenVMS usage _ floating_point 


type G_floating, H_floating 
access write only 
mechanism by reference 


OTS$SCVT_T_z 


Floating-point value that OTS$CVT_T_z creates when it converts the input 
string. The floating-point-value argument is the address of the floating-point 
value. For OTS$CVT_T_G, floating-point-value is a G-floating number. For 
OTS$CVT_T_H, floating-point-value is an H-floating number. 


digits-in-fraction 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
-mechanism by value 


Number of digits in the fraction if no decimal point is included in the input string. 
The digits-in-fraction argument contains the number of digits. If the number of 
digits is omitted, the default is zero. 


scale-factor 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism | by value 


Scale factor. The scale-factor argument contains the value of the scale factor. 
If bit 6 of the flags-value argument is clear, the resultant value is divided by 
10scale—factor unless the exponent is present. If bit 6 of flags-value is set, the 
scale factor is always applied. If the scale factor is omitted, the default is zero. 


flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags. The flags-value argument contains the user-supplied flags. 


Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z 
interprets blanks as zeros. 
Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If clear, 


OTS$CVT_T_z allows E, e, D, d, Q, and q exponents. (Bit 1 is clear 
for BASIC and set for FORTRAN.) 


Bit 2 If set, OTS$CVT_T_z interprets an underflow as an error. If clear, 
OTS$CVT_T_z does not interpret an underflow as an error. 

Bit 3 If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_T-z 
rounds the value. 

Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets 
tabs as invalid characters. 

Bit 5 If set, an exponent must begin with a valid exponent letter. If clear, 
the exponent letter may be omitted. 

Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If clear, 


OTS$CVT_T_z applies the scale factor only if there is no exponent 
present in the string. 


If flags-value is omitted, all bits are clear. 
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Description 


extension-bits 
OpenVMS usage word_signed ~ 


type word (signed) 
access write only 
mechanism by reference 


Extra precision bits. The extension-bits argument is the address of a signed 
word integer containing the extra precision bits. If present, floating-point-value 
is not rounded, and the first n bits after truncation are returned in this argument. 
For G-floating and H-floating, n equals 11 and 15, respectively, and the bits are 
returned as a word, left-justified. | 


These values are suitable for use as the extension operand in an EMOD 
instruction. 


The extra precision bits returned for H-floating may not be precise because 
calculations are only carried to 128 bits. However, the error should be small. 


These routines support FORTRAN D, E, F, and G input type conversion as well 
as similar types for other languages. 


OTS$CVT_T_G and OTS$CVT_T_H provide run-time support for BASIC and 
FORTRAN input statements. 


Condition Values Returned 
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SS$_ NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error; an invalid character in 
the input string, or the value is outside the range 
that can be represented. Floating-point-value 
is set to +0.0 (not reserved operand —0.0). 


OTS$CVT_TZ_L 


OTS$CVT_TZ_L—Convert Hexadecimal Text to Unsigned Integer 


Format 


Returns 


Arguments 


The Convert Hexadecimal Text to Unsigned Integer routine converts an ASCII 
text string representation of an unsigned hexadecimal value to an unsigned 
integer of an arbitrary length. The result is a longword by default, but the calling 
program can specify a byte, word, or longword value. 


_ OTS$CVT_TZ_L  fixed-or-dynamic-input-string ,varying-output-value 


[,output-value-size] [,flags-value] 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


fixed-or-dynamic-input-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor, fixed-length or dynamic string 


Input string containing an ASCII text string representation of an unsigned 
hexadecimal value that OTS$CVT_TZ_L converts to an unsigned integer. The 
fixed-or-dynamic-input-string argument is the address of a descriptor pointing 
to the input string. Valid input characters are the space, the digits 0 through 9, 
and the letters A through F (lowercase letters a through f are acceptable). No 
sign is permitted. 


varying-output-value 
OpenVMS usage varying_arg 


type unspecified 
access write only 
mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TZ_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


output-value-size 
OpenVMS usage _ longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Number of bytes occupied by the integer value. The output-value-size argument 
contains the number of bytes. If the value size is zero or a negative number, 
OTS$CVT_TZ_L returns an input conversion error. If the number of bytes is 
omitted, the default is 4 (longword). 
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flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 
access read only 
mechanism by value 


User-supplied flags that OTS$CVT_TZ_L uses to determine how blanks are 


interpreted. 


The flags-value argument is an unsigned longword containing these 


user-supplied flags. 


Bit 0 If set, OTS$CVT_TZ_L ignores blanks. If clear, OTS$CVT_TZ_L 
interprets blanks as zeros. 


If flags-value is omitted, the default is that all bits are clear. 


Condition Values Returned 


Examples 
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SS$ NORMAL Normal successful completion. 
OTS$_INPCONERR Input conversion error. An invalid character, 


100 


overflow, or invalid output-value-size occurred. 


Le 
! This BASIC program converts a character string representing 
! a hexadecimal value to a longword. 


I+ | 
! Tllustrate (and test) OTS convert hex-string to longword 


EXTERNAL LONG FUNCTION OTSSCVT_TZ_L 

EXTERNAL LONG CONSTANT OTSS_INPCONERR 

INPUT "Enter hex numeric";HEXVALS 

RET_STAT% = OTSSCVT_TZ_L(HEXVALS, HEX ) 

PRINT "Conversion error " IF RET_STAT% = OTSS_INPCONERR 

PRINT "Decimal value of ";HEXVALS;" is";HEX% & 
IF RET_STAT% <> OTSS_INPCONERR 


This BASIC example accepts a hexadecimal numeric string, converts it to a 
decimal integer, and prints the result. One sample of the output generated by 
this program is as follows: © | 


S RUN HEX 
Enter hex numeric? A 


Decimal 


value of A is 10 


2. HEX_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 


SINCLUDE SSTSDEF; /* Include definition of return status values 1d | 

DECLARE OTSSCVT_TZ_L ENTRY 
(CHARACTER (*), /* Input string passed by descriptor */ 
FIXED BINARY (31), /* Returned value passed by reference <7 
FIXED BINARY VALUE, /* Size for returned value passed by value */ 
FIXED BINARY VALUE) /* Flags passed by value a 
RETURNS (FIXED BINARY (31)) /* Return status i 
OPTIONS (VARIABLE) ; /* Arguments may be omitted | 

DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 


DECLARE 


FLAGS FIXED BINARY (31) INITIAL(1) READONLY STATIC; /* Ignore blanks */ 


OTS$CVT_TZ_L 


ON ENDFILE (SYSIN) STOP; 


DO WHILE (‘1'B); /* Loop continuously, until end of file lt 
PUT SKIP (2); 
GET LIST (INPUT) OPTIONS (PROMPT (‘Hex value: ')); 
STSSVALUE = OTSSCVT_TZ_L (INPUT, VALUE, , FLAGS); 
IF “STSSSUCCESS THEN RETURN (STSSVALUE) ; 
PUT SKIP EDIT (INPUT, ‘Hex equals’, VALUE, ‘Decimal’) 
(A,X,A,X,F(10),X,A); 
END; 


END HEX_CONV; 


This PL/I example translates a hexadecimal value in ASCII into a fixed 
binary value. This program continues to prompt for input values until the 
user types Ctrl/Z. : 


One sample of the output generated by this program is as follows: 


S RUN HEX 
Hex value: 1A | 
1A Hex equals 26 Decimal 


Hex value: C 
C Hex equals 12 Decimal 


Hex value: Ctrl/Z 
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OTS$DIVCx—Complex Division 


Format 


Returns 


Arguments 
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The Complex Division routines return a complex result of a division on complex 
numbers. 


OTS$DIVC complex-dividend ,complex-divisor 
OTS$DIVCD_R3_ complex-dividend ,complex-divisor 
OTS$DIVCG_R3_ complex-dividend ,complex-divisor 


Each of these three formats corresponds to one of the three floating-point complex 
types. 


OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_floating complex 
access write only 
mechanism by value 


Complex result of complex division. OTS$DIVC returns an F-floating complex 
number. OTS$DIVCD_R3 returns a D-floating complex number. OTS$DIVCG_R3 
returns a G-floating complex number. 


complex-dividend 
OpenVMS usage complex_number 


type EF’ floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by value 


Complex dividend. The complex-dividend argument contains a floating-point 
complex value. For OTS$DIVC, complex-dividend is an F-floating complex 
number. For OTS$DIVCD_R3, complex-dividend is a D-floating complex 
number. For OTS$DIVCG_R3, complex-dividend is a G-floating complex 
number. 


complex-divisor 
OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_ floating complex 
access read only 
mechanism by value 


Complex divisor. The complex-divisor argument contains the value of the 

divisor. For OTS$DIVC, complex-divisor is an F-floating complex number. 

For OTS$DIVCD_R3, complex-divisor is a D-floating complex number. For 
OTS$DIVCG_R3, complex-divisor is a G-floating complex number. 


Description 


OTS$DIVCx 


These routines return a complex result of a division on complex numbers. 
The complex result is computed as follows: 

1. Let (a,b) represent the complex dividend. 

2. Let (c,d) represent the complex divisor. 

3. Let (7,1) represent the complex quotient. 


The results of this computation are as follows: 


r = (ac + bd) /(c* + d?) 


i = (be — ad) /(c* + d?) 


Condition Values Signaled 


Examples 


SS$_FLTDIV_F Arithmetic fault. Floating-point division by zero. 
SS$_FLTOVF_F Arithmetic fault. Floating-point overflow. 


C+ 
C This FORTRAN example forms the complex 
C quotient of two complex numbers using 
Cc OTSSDIVC and the FORTRAN random number 
C generator RAN. 
c 
C Declare Z1, Z2, Z2_0, and OTSSDIVC as complex values. 
C OTSSDIVC will return the complex quotient of Z1 divided 
C by Z2: 2Z_Q = OTSSDIVC( @VAL(REAL(Z1)), @VAL(AIMAG(Z1), 
C $VAL(REAL(Z2)), SVAL(AIMAG(Z2) } 
C- 
COMPLEX Z1,2Z2,Z_0,OTSSDIVC 
C+ 
6 Generate a complex number. 
C- 
Dh Se AB e0 a0) 
C+ 
C Generate another complex number. 
C- 
fa (1 Oe a 0) 
C+ 
a Compute the complex quotient of 21/22. 
C- 
Z_Q = OTSSDIVC( $VAL(REAL(Z1)), %VAL(AIMAG(Z1)), t@VAL(REAL(Z2)), 
+ SVAL (AIMAG (Z2) ) ) 
TYPE *, ' The complex quotient of’,Z1,' divided by ',Z2,’ is’ 
TYPE: *,.. 2 rey ae: 
END 


This FORTRAN program demonstrates how to call OTS$DIVC. The output 
generated by this program is as follows: 


The complex quotient of (8.000000,4.000000) divided by (1.000000,1.000000) 
is (6.000000,-2.000000) 
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C- 


C+ 


C- 


C+ 


C- 


This FORTRAN example forms the complex 
quotient of two complex numbers by using 
OTSSDIVCG_R3 and the FORTRAN random number 
generator RAN. 
Declare Z1, 22, and Z_Q as complex values. OTSSDIVCG_R3 


will return the complex quotient of Z1 divided by Z2: 
ZO =. OL 22 


COMPLEX*16 Z1,2Z2,Z_Q 
Generate a complex number. 
Zi. = (850)4. 0) 
Generate another complex number. 
22-2 (1,052.0) 


Compute the complex quotient of 21/22. 


BOS 71772 

TYPE *, ‘ The complex quotient of’,Z1,' divided by ',22,’ is’ 
TYPE; PTO 

END 


This FORTRAN example uses the OTS$DIVCG_R3 entry point instead. 
Notice the difference in the precision of the output generated: 


The complex quotient of (8.000000000000000,4.000000000000000) divided by 
(1.000000000000000,1.000000000000000) is 


(6 .000000000000000,-2.000000000000000) 
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OTS$DIV_PK_LONG—Packed Decimal Division with Long Divisor 


Format 


Returns 


Arguments 


The Packed Decimal Division with Long Divisor routine divides fixed-point 
decimal data, which is stored in packed decimal form, when precision and scale 
requirements for the quotient call for multiple precision division. The divisor 
must have a precision of thirty or thirty-one digits. 


OTS$DIV_PK_LONG _ packed-decimal-dividend ,packed-decimal-divisor 
,divisor-precision ,packed-decimal-quotient ,quotient-precision 
,sprecision-data ,scale-data 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


packed-decimal-dividend 
OpenVMS usage varying_arg 


type packed decimal string 
access read only 
mechanism by reference 


Dividend. The packed-decimal-dividend argument is the address of a packed 
decimal string that contains the shifted dividend. 


Before being passed as input, the packed-decimal-dividend argument is always 
multiplied by 10° where c is defined as follows: 


c = 31 - prec(packed-decimal-dividend) 


Mutiplying packed-decimal-dividend by 10° makes packed-decimal- 
dividend a 31-digit number. 


packed-decimal-divisor 
OpenVMS usage varying_arg 


type packed decimal string 
access read only 
mechanism by reference 


Divisor. The packed-decimal-divisor argument is the address of a packed 
decimal string that contains the divisor. 


divisor-precision 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Precision of the divisor. The divisor-precision argument is a signed word that 
contains the precision of the divisor. The high-order bits are filled with zeros. 
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packed-decimal-quotient 


OpenVMS usage 
type 

access 
mechanism 


varying_arg 

packed decimal string 
write only 

by reference 
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Quotient. The packed-decimal-quotient argument is the address of the packed 
decimal string into which OTS$DIV_PK_LONG writes the quotient. 


quotient-precision 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Precision of the quotient. The quotient-precision argument is a signed word 
that contains the precision of the quotient. The high-order bits are filled with 
zeros. 


precision-data 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Additional digits of precision required. The precision-data argument is a signed 
word that contains the value of the additional digits of precision required. 


OTS$DIV_PK_LONG computes the precision-data argument as follows: 


precision-data = scale(packed-decimal-quotient) 
+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

- 31 + prec (packed-decimal-dividend) 


scale-data 

OpenVMS usage word_signed 
type word (signed) 
access read only 
mechanism by value 


Scale factor of the decimal point. The scale-data argument is a signed word that 
contains the scale data. 


OTS$DIV_PK_LONG defines the scale-data argument as follows: 


scale-data = 31 - prec(packed-decimal-divisor) 


Description 


<i> 


OTS$DIV_PK_LONG 


Before using this routine on an OpenVMS for VAX system, you should determine 
whether it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the 
VAX instruction DIVP. To determine this, you must first calculate 6, where b is 
defined as follows: 


b = scale (packed-decimal-quotient) 
+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

+ prec (packed-decimal-dividend) 


If b is greater than 31, then OTS$DIV_PK_LONG can be used to perform the 
division. If 6 is less than 31, you could use the instruction DIVP instead. ¢ 


When using this routine on an OpenVMS AXP system, or on an OpenVMS 
VAX system and you have determined that you cannot use DIVP, you need 

to determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_ 
SHORT. To determine this, you must examine the value of scale-data. If scale- 
data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_SHORT instead. 


Condition Value Signaled 


Example 


SS$_FLTDIV Fatal error. Division by zero. 


OPTION —& 
TYPE = EXPLICIT 


! This program uses OTSSDIV_PK_LONG to perform packed decimal 


! division. 

= 

I+ 

! DECLARATIONS 

_ 

DECLARE DECIMAL (31, 2) NATIONAL_DEBT 
DECLARE DECIMAL (30, 3) POPULATION 
DECLARE DECIMAL (10, 5) PER_CAPITA_DEBT 


EXTERNAL SUB OTSSDIV_PK_LONG (DECIMAL(31,2), DECIMAL (30, 3), & 
WORD BY VALUE, DECIMAL(10, 5), WORD BY VALUE, WORD BY VALUE, & 
WORD BY VALUE) 


We 
! Prompt the user for the required input. 


INPUT "Enter national debt: ";NATIONAL_DEBT 
INPUT "Enter current population: ";POPULATION 
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Perform the division and print the result. 


b is greater than 31, so either OTSSDIV_PK_LONG or 
OTSSDIV_PK_SHORT may be used to perform the division. 
If b is less than or equal to 31, then the DIVP 
instruction may be used. 


scale-data is less than or equal to 1, so OTSSDIV_PK_LONG 
should be used instead of OTSSDIV_PK_SHORT. 


: 

! scale(divd) = 2 

! scale(divr) = 3 

! gcale(quot) = 5 

I 

! prec(divd) = 31 

! prec(divr) = 30 

!  prec(quot) = 10 

! 

! prec-data = scale(quot) + scale(divr) - scale(divd) - 31 + 
prec (divd) 

!  prec-data = 5 - 42 = 2 - 314 31 
! prec-data = 6 

I 

! b= scale(quot) + scale(divr) - scale(divd) + prec(divd) 
Yr be 5 + 3 = 2 + 31 

PbS 37 

I 

! ¢ = 31 - prec(divd) 

b S2e3he: 31 

bP CS 

| 

! gcale-data = 31 - prec(divr) 

|! scale-data = 31 - 30 

! sceale-data = 1 

I 

: 

! 

: 


CALL OTSSDIV_PK_LONG( NATIONAL_DEBT, POPULATION, ‘30’W, PER_CAPITA_DEBT, & 
PLO We OPW, FW) 


PRINT "The per capita debt is ";PER_CAPITA_DEBT 
END 


This BASIC example program uses OTS$DIV_PK_LONG to perform packed 
decimal division. One example of the output generated by this program is as 
follows: 


S RUN DEBT 

Enter national debt: ? 12345678 
Enter current population: ? 1212 
The per capita debt is 10186.20297 
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OTS$DIV_PK_SHORT 


OTSSDIV_PK_SHORT—Packed Decimal Division with Short Divisor 


Format 


Returns 


Arguments 


The Packed Decimal Division with Short Divisor routine divides fixed-point 
decimal data when precision and scale requirements for the quotient call for 
multiple-precision division. 


OTS$DIV_PK_SHORT  packed-decimal-dividend ,packed-decimal-divisor 
,divisor-precision ,packed-decimal-quotient 
,quotient-precision ,precision-data 


OpenVMS usage cond_value 


type longword (unsigned) 
access write only 
mechanism by value 


packed-decimal-dividend 
OpenVMS usage varying_arg 


type packed decimal string 
access read only | 
mechanism by reference 


Dividend. The packed-decimal-dividend argument is the address of a packed 
decimal string that contains the shifted dividend. 


Before being passed as input, the packed-decimal-dividend argument is always 
multiplied by 10° where c is defined as follows: 


c = 31 - prec(packed-decimal-dividend) 


Multiplying packed-decimal-dividend by 10° makes packed-decimal- 
dividend a 31-digit number. 


packed-decimal-divisor 
OpenVMS usage varying_arg 


type packed decimal string 
access read only 
mechanism by reference 


Divisor. The packed-decimal-divisor argument is the address of a packed 
decimal string that contains the divisor. 


divisor-precision | 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Precision of the divisor. The divisor-precision argument is a signed word 
integer that contains the precision of the divisor. The high-order bits are filled 
with zeros. 
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OTS$DIV_PK_SHORT 


Description 


<i> 
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packed-decimal-quotient 
OpenVMS usage varying_arg 


type packed decimal string 
access write only 
mechanism by reference 


Quotient. The packed-decimal-quotient argument is the address of a packed 
decimal string into which OTS$DIV_PK_SHORT writes the quotient. 


quotient-precision 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Precision of the quotient. The quotient-precision argument is a signed word 
that contains the precision of the quotient. The high-order bits are filled with 
Zeros. 


precision-data 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Additional digits of precision required. The precision-data argument is a signed 
word that contains the value of the additional digits of precision required. 


OTS$DIV_PK_SHORT computes the precision-data argument as follows: 


precision-data = scale(packed-decimal-quotient) 
+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

- 31 + prec (packed-decimal-dividend) 


Before using this routine on an OpenVMS for VAX system, you should determine 
whether it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the 
VAX instruction DIVP. To determine this, you must first calculate 6, where 6 is 
defined as follows: . 


b = scale (packed-decimal-quotient) + scale(packed-decimal-divisor) - 
scale (packed-decimal-dividend) + prec (packed-decimal-dividend) 


If b is greater than 31, then OTS$DIV_PK_SHORT can be used to perform the 
division. If 5 is less than 31, you could use the VAX instruction DIVP instead. ¢ 


When using this routine on an OpenVMS AXP system, or on an OpenVMS 

for VAX system and you have determined that you cannot use DIVP, you need 
to determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_ 
SHORT. To determine this, you must examine the value of scale-data. If scale- 
data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_ SHORT instead. 


OTS$DIV_PK_SHORT 


Condition Value Signaled 


SS$ FLTDIV Fatal error. Division by zero. 
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OTS$MOVE3—WMove Data Without Fill 


Format 


The Move Data Without Fill routine moves up to 2°!—1 bytes (2,147,483,647 
bytes) from a specified source address to a specified destination address. 


OTS$MOVE3 _length-value ,source-array ,destination-array 


corresponding jsb entry point 


Returns 


Arguments 
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OTS$MOVE3_R5 


None. 

length-value 

OpenVMS usage longword_signed 
type longword (signed) 
access read only 
mechanism by value 


Number of bytes of data to move. The length-value argument is a signed 
longword that contains the number of bytes to move. The value of fonetnwalue 
may range from 0 to 2,147,483,647 bytes. 


source-array 
OpenVMS usage _  vector_byte_unsigned 


type byte (unsigned) 
access read only 
mechanism by reference, array reference 


Data to be moved by OTS$MOVES. The source-array argument contains the 
address of an unsigned byte array that contains this data. 


destination-array 
OpenVMS usage  vector_byte_unsigned 


type byte (unsigned) 
access write only 
mechanism by reference, array reference 


Address into which source-array will be moved. The destination-array 
argument is the address of an unsigned byte array into which OTS$MOVE3 
writes the source data. 


OTS$MOVE3 


Description 


OTS$MOVES3 performs the same function as the VAX MOVCS instruction except 
that the length-value is a longword integer rather than a word integer. When 
called from the JSB entry point, the register outputs of OTS$MOVE3_R5 follow 
the same pattern as those of the MOVC3 instruction: 


RO 0 
R1 Address of one byte beyond the source string 
R2 0 
R3 Address of one byte beyond the destination string 
R4 0 
R5 0 


For more information, see the description of the MOVC8 instruction in the VAX 
Architecture Reference Manual. See also the routine LIB$MOVC3, which is a 
callable version of the MOVC3 instruction. 


Condition Values Returned 


None. 
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OTSS$MOVE5—Move Data with Fill 


Format 


The Move Data with Fill routine moves up to 2°!—1 bytes (2,147,483,647 
bytes) from a specified source address to a specified destination address, with 
separate source and destination lengths, and with fill. Overlap of the source and 
destination arrays does not affect the result. 


OTS$MOVES5 _longword-int-source-length ,source-array ,fill-value 
,longword-int-dest-length ,destination-array 


corresponding jsb entry point 


Returns 


Arguments 
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OTS$MOVE5_R5 
None. 


longword-int-source-length 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Number of bytes of data to move. The longword-int-source-length argument 
is a signed longword that contains this number. The value of longword-int- 
source-length may range from 0 to 2,147,483,647. 


source-array 
OpenVMS usage _  vector_byte_unsigned 


type byte (unsigned) 
access read only 
mechanism by reference, array reference 


Data to be moved by OTS$MOVE5. The source-array argument contains the 
address of an unsigned byte array that contains this data. 


fill-value 

OpenVMS usage byte_unsigned 
type byte (unsigned) 
access read only 
mechanism by value 


Character used to pad the source data if longword-int-source-length is less 
than longword-int-dest-length. The fill-value argument contains the address 
of an unsigned byte that is this character. 


longword-int-dest-length 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


OTSSMOVES5 


Size of the destination area in bytes. The longword-int-dest-length argument 
is a signed longword containing this size. The value of longword-int-dest- 
length may range from 0 through 2,147,483,647. 


destination-array 
OpenVMS usage _ vector_byte_unsigned 


type byte (unsigned) 
access write only 
mechanism by reference, array reference 


Address into which source-array is moved. The destination-array argument is 
the address of an unsigned byte array into which OTS$MOVE5 writes the source 
data. 


Description 


OTS$MOVE5 performs the same function as the VAX MOVCS instruction 
except that the longword-int-source-length and longword-int-dest-length 
arguments are longword integers rather than word integers. When called from 
the JSB entry point, the register outputs of OTS$MOVE5_R5 follow the same 
pattern as those of the MOVC5 instruction: 


RO Number of unmoved bytes remaining in source string 
Ri Address of one byte beyond the source string 

R2 0 a: 

R3 Address of one byte beyond the destination string 

R4 0 

R5 0 


For more information, see the description of the MOVC5 instruction in the VAX 
Architecture Reference Manual. See also the routine LIB$MOVC5, which is a 
callable version of the MOVC5 instruction. 


Condition Values Returned 


None. 


OTS-51 


OTSS$MULCx 


OTS$MULCx—Complex Multiplication 


Format 


Returns 


Arguments 


Description 
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The Complex Multiplication routines calculate the complex product of two 
complex values. 


OTS$MULCD_R3_ complex-multiplier ,complex-multiplicand 
OTS$MULCG_R3_ complex-multiplier ,;complex-multiplicand 
These formats correspond to the D-floating and G-floating complex types. 


OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access write only 
mechanism by value 


Complex result of multiplying two complex numbers. OTS$MULCD_R38 returns 
a D-floating complex number. OTS$MULCG_R3 returns a G-floating complex 
number. 


complex-multiplier 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism by value 


Complex multiplier. The complex-multiplier argument contains the complex 
multiplier. For OTS$MULCD_R3, complex-multiplier is a D-floating complex 
number. For OTS$MULCG_R3, complex-multiplier is a G-floating complex 
number. 


complex-multiplicand 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism — by value 


Complex multiplicand. The complex-multiplicand argument contains the 
complex multiplicand. For OTS$MULCD_R3, complex-multiplicand is a D- 
floating complex number. For OTS$MULCG_R3, complex-multiplicand is an 
F-floating complex number. 


OTS$MULCD_R3 and OTS$MULCG_R38 calculate the complex product of two 


complex values. 
The complex product is computed as follows: 
1. Let (a,b) represent the complex multiplier. 


2. Let (c,d) represent the complex multiplicand. 


OTS$MULCx 


3. Let (r,i) represent the complex product. 


The results of this computation are as follows: 
(a,b) * (c,d) = (ac — bd) + V—1(ad + bc) 


Therefore: r= ac-— bd 
Therefore:1 = ad-+ be 


Condition Values Signaled 


Example 


SS$_FLTOVF_F Floating value overflow can occur. 


SS$_ROPRAND Reserved operand. OTS$MULCx encountered 
a floating-point reserved operand because of 
incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
Digital. 


C+ 
C This FORTRAN example forms the product of 
C two complex numbers using OTSSMULCD_R3 
C and the FORTRAN random number generator RAN. 
C 
C Declare Z1, Z2, and Z_Q as complex values. OTSSMULCD_R3 
C returns the complex product of Z1 times 22: 
C LA) SF RZ 
C- 
COMPLEX*16 Z1,22,Z_0 
C+ 
C Generate a complex number. 
C- 
Zl) 2? 480,430) 
C+ 
C Generate another complex number. 
C- 
Z2 = (220.320) 
C+ 
C Compute the complex product of Z1*Z2. 
C- 
AOS Ol 22 
TYPE: *, “© ‘The: complex product: OF 271," tames: "4.72," 1S" 
TYPE, ~ ‘ge O 
END 


This FORTRAN example uses OTS$MULCD_R3 to multiply two complex 
numbers. The output generated by this program is as follows: 


The complex product of (8.000000000000000,4.000000000000000) times 
(2.000000000000000,3.000000000000000) is 
(4.000000000000000, 32.00000000000000) 


OTSA 
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OTS$POWCxCx—Raise a Complex Base to a Complex Floating-Point 


Format 


Returns 


Arguments 
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Exponent 


The Raise a Complex Base to a Complex Floating-Point Exponent routines raise a 
complex base to a complex exponent. 


OTS$POWCC complex-base ,complex-exponent-value 
OTS$POWCDCD_R3_ complex-base ,complex-exponent-value 
OTSSPOWCGCG_R3_ complex-base ,complex-exponent-value 


Each of these three formats corresponds to one of the three floating-point complex 
types. 


OpenVMS usage complex_number 


type EF’ floating complex, D_floating complex, G_floating complex 
access write only 
mechanism by value 


Result of raising a complex base to a complex exponent. OTS$POWCC returns 
an F-floating complex number. OTS$POWCDCD_R3 returns a D-floating a 
number. OTS$POWCGCG_R3 returns a G-floating complex number. 


complex-base 
OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by value 


Complex base. The complex-base argument contains the value of the base. 
For OTS$POWCC, complex-base is an F-floating complex number. For 
OTS$POWCDCD_R3, complex-base is a D-floating complex number. For 
OTS$POWCGCG_R3, complex-base is a G-floating complex number. 


complex-exponent-value 
OpenVMS usage complex_number 


type EF’ floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by value 


Complex exponent. The complex-exponent-value argument contains the value 
of the exponent. For OTS$POWCC, complex-exponent-value is an F-floating 
complex number. For OTS$POWCDCD_R3, complex-exponent-value is a 
D-floating complex number. For OTS$POWCGCG_R3, complex-exponent-value 
is a G-floating complex number. 


Description 


OTSSPOWCxCx 


OTS$POWCC, OTS$POWCDCD_R3 and OTS$POWCGCG_R3 raise a complex 
base to a complex exponent. The American National Standard FORTRAN-—77 
(ANSI X38.9-1978) defines complex exponentiation as follows: 

a! = exp(y * log(z)) 


In this example, x and y are type COMPLEX. 


Condition Values Signaled 


Examples 


MTH$_INVARGMAT Invalid argument in math library. Base is (0.,0.). 
MTH$_FLOOVEMAT Floating-point overflow in math library. 
SS$_ROPRAND Reserved operand. 
1. C+ 
C This FORTRAN example raises a complex base to a complex 
C power using OTSSPOWCC. 
C 
C Declare Z1, 22, Z3, and OTSSPOWCC as complex values. Then OTSSPOWCC 
iG returns the complex result of Z1**Z2: 23 = OTSSPOWCC(Z1,Z2), 
C where Z1 and Z2 are passed by value. 
C- 
COMPLEX Z21,22,Z3,OTSSPOWCC 
C+ 
C Generate a complex base. 
C- 
ZL = 4205 320) 
C+ 
C Generate a complex power. 
C- 
Lar Se AL Oe? 30) 
C+ 
C Compute the complex value of Z1**Z2. 
C- 
Z3 = OTSSPOWCC( *VAL(REAL(Z1)), @VAL(AIMAG(Z1)), 
+ $VAL(REAL(Z2)), VAL (AIMAG(Z2) ) ) 
TY DES 7 he va lie Of" Fd, Pee 22 er ers 
END 


This FORTRAN example uses OTS$POWCC to raise an F-floating complex 
base to an F-floating complex exponent. 


The output generated by this program is as follows: 


The value of (2.000000,3.000000)** (1.000000,2.000000) is 
(=0,46595605,=0.1995301) 
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OTS$POWCxCx 
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C+ 
6 This FORTRAN example raises a complex base to a complex 
C power using OTSSPOWCGCG_R3. 
C 
C Declare Z1, 22, and Z3 as complex values. OTSSPOWCGCG_R3 
C returns the complex result of Z1**Z2: Z3 = Z1**Z2. 
C- 
COMPLEX*16 Z1,22,23 
C+ 
C Generate a complex base. 
C- 
ZL =: (230,30) 
C+ 
C Generate a complex power. 
C- 
| id = A 30) 
C+ 
C Compute the complex value of Z1**Z2. 
C- 
23-2 DEE 72 


TYPE eZ ln 
1 FORMAT(’ The value of (‘',F11.8,',',F11.8,')**('’,F11.8, 
pe Le aS. pe he Oye Oh Leo etd 
END 


This FORTRAN example program shows how to use OTS$POWCGCG_R3. 
Notice the high precision in the output generated by this program: 


The value of ( 2.00000000, 3.00000000)**( 1.00000000, 2.00000000) is 
(-0.46395650,-0.46395650) . 
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OTS$POWCxJ—Raise a Complex Base to a Signed Longword Integer 


Format 


Returns 


Arguments 


Exponent 


The Raise a Complex Base to a Signed Longword Integer Exponent routines 
return the complex result of raising a complex base to an integer exponent. 


OTS$POWCJ complex-base ,longword-integer-exponent 
OTS$POWCDJ_R3_ complex-base ,longword-integer-exponent 
OTS$POWCGJ_R3_ complex-base ,longword-integer-exponent 


Each of these three formats corresponds to one of the three floating-point complex 
types. 


OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_floating complex 
access write only 
mechanism by value 


Complex result of raising a complex base to an integer exponent. OTS$POWCJ 
returns an F-floating complex number. OTS$POWCDJ_R3 returns a D-floating 
complex number. OTS$POWCGJ_R3 returns a G-floating complex number. In 
each format, the result and base are of the same data type. 


complex-base 
OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_floating complex 
access read only | 
mechanism by value 


Complex base. The complex-base argument contains the complex base. 
For OTS$POWCJ, complex-base is an F-floating complex number. For 
OTS$POWCDJ_R3, complex-base is a D-floating complex number. For 
OTS$POWCGJ_R3, complex-base is a G-floating complex number. 


longword-integer-exponent 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism _ by value 


Exponent. The longword-integer-exponent argument is a signed longword 
containing the exponent. 
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OTS$POWCxJ 


Description 


OTS$POWCJ, OTS$POWCDJ_R3, and OTS$POWCGJ_R3 return the complex 
result of raising a complex base to an integer exponent. The complex result is as 


Condition Values Signaled 


Example 
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follows: 

Base Exponent Result 

Any >0 The product of (base**2'), where i is each nonzero 
| bit in longword-integer-exponent 

(0.,0.) <0 Undefined exponentiation 

Not (0.,0.) <0 The product of (base**2'), where i is each nonzero 

bit in longword-integer-exponent 

Not (0.,0.) 0 (1.0,0.0) 

SS$_FLTDIV | Floating-point division by zero. 

SS$_FLTOVF Floating-point overflow. 

MTH$_ UNDEXP Undefined exponentiation. 


+ 


lAMlAAARAMmAAMANN 


C- 
C+ 


C- 


C+ 


C- 


The 


This FORTRAN example raises a complex base to 
a NONNEGATIVE integer power using OTSSPOWCJ. 


Declare Z1, Z2, Z3, and OTSSPOWCJ as complex values. 
Then OTSSPOWCJ returns the complex result of 

LEEK OS Z3 = OTSSPOWCJ(Z1,22), 

where Zl and Z2 are passed by value. 


COMPLEX 21,2Z3,0TS$POWCJ 
INTEGER Z2 


Generate a complex base. 
71. = (23505.3%.0) 
Generate an integer power. 


Le = 2 


Compute the complex value of Z1**Z2. 


Z3 = OTSSPOWCU( *%VAL(REAL(Z1)), SVAL(AIMAG(Z1)), SVAL(Z2) ) 
TYPE L521; 22;.23 
FORMAT(’ The value of (‘,F10.8,',',F11.8,‘)**',1I1,' is 
f° CR Ot Plo Ge pe) 
END 


output generated by this FORTRAN program is as follows: 


The value of (2.00000000, 3.00000000)**2 is 


(-5.00000000, 12.00000000). 
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OTS$POWDD—Raise a D-Floating Base to a D-Floating Exponent 


Format 


Returns 


Arguments 


Description 


The Raise a D-Floating Base to a D-Floating Exponent routine raises a D-floating 
base to a D-floating exponent. 


OTS$POWDD  D-floating-point-base ,D-floating-point-exponent 


OpenVMS usage  floating_point 


type D_floating 
access write only 
mechanism by value 


D-floating-point-base 
OpenVMS usage  floating_point 


type D_floating 
access read only 
mechanism by value 


Base. The D-floating-point-base argument is a D-floating number containing 
the base. 


D-floating-point-exponent 
OpenVMS usage _ floating_point 


type D_floating 
access read only 
mechanism by value 


Exponent. The D-floating-point-exponent argument is a D-floating number 
that contains the exponent. 


OTS$POWDD raises a D-floating base to a D-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The D-floating result for OTS$POWDD is given by the following: 


Base Exponent Result 

= 0 >0 0.0 

= 0 = 0 Undefined exponentiation 
= 0 <0 Undefined exponentiation 
<0 Any Undefined exponentiation 
>0 > 0 glexponent+log2(base)] 

>0 = 0 1.0 
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OTSSPOWDD 


Base Exponent Result 


> 0 <0 glexponent+log2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 
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'. MTH$_FLOOVEMAT Floating-point overflow in math library. 
MTH$ FLOUNDMAT Floating-point underflow in math library. 
MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if D-floating-point-base is zero and D-floating- 
point-exponent is zero or negative, or if the 
D-floating-point-base is negative. 


OTSSPOWDR 


OTS$POWDR—Raise a D-Floating Base to an F-Floating Exponent 


Format 


Returns 


Arguments 


Description 


The Raise a D-Floating Base to an F-Floating Exponent routine raises a D- 
floating base to an F-floating exponent. 


OTS$POWDR_ D-floating-point-base ,F-floating-point-exponent 


OpenVMS usage floating_point 


type D_floating 
access write only 
mechanism by value 


D-floating-point-base 
OpenVMS usage floating_point 


type D_floating 
access read only 
mechanism by value 


Base. The D-floating-point-base argument is a D-floating number containing 
the base. 


F-floating-point-exponent 
OpenVMS usage floating_point 


type F_floating 
access read only 
mechanism by value 


Exponent. The F-floating-point-exponent argument is an F-floating number 
that contains the exponent. 


OTS$POWDR raises a D-floating base to an F-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. | 


OTS$POWDR converts the F-floating exponent to a D-floating number. The 
D-floating result for OTS$POWDR is given by the following: 


Base Exponent Result 

= 0 >0 0.0 

=an@ = 0 Undefined exponentiation 
=( <0 Undefined exponentiation 
<0 Any Undefined exponentiation 
> 0 >0 olexponent+log2(base)] 

> 0 = 0 1.0 
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OTSSPOWDR 


Base Exponent 


> 0 <0 


olexponentxlog2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 
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SS$_FLTOVF 


MTH$_FLOOVEMAT 
MTH$_FLOUNDMAT 
MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overfiow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponentiation. This error is signaled 
if D-floating-point-base is zero and F-floating- 
point-exponent is zero or negative, or if the 
D-floating-point-base is negative. 


OTSS$POWDJ 


OTS$POWDJ—Raise a D-Floating Base to a Longword Exponent 


Format 


Returns 


Arguments 


Description 


The Raise a D-Floating Base to a Longword Exponent routine raises a D-floating 
base to a longword exponent. 


OTS$POWDJ_ D-floating-point-base ,longword-integer-exponent 


OpenVMS usage _ floating_point 


type D_floating 
access write only 


mechanism by value 


D-floating-point-base 
OpenVMS usage _ floating_point 


type D_floating 
access read only 
mechanism by value 


Base. The D-floating-point-base argument is a D-floating number containing 
the base. 


longword-integer-exponent 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Exponent. The longword-integer-exponent argument is a signed longword 
that contains the signed longword integer exponent. 


OTS$POWD2 raises a D-floating base to a longword exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The floating-point result is as follows: 


Base Exponent Result 

Any >0 Product of (base**2') where i is each nonzero bit 
position in longword-integer-exponent 

>0 =0 1.0 | 

= = 0 Undefined exponentiation 

<0 = 0 1.0 

>0 <0 1.0/ (base**2"), where i is each nonzero bit position in 


longword-integer-exponent 
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Base Exponent 
=0 <0 
<0 <0 


Result 


Undefined exponentiation 


1.0/ (base**2') where i is each nonzero bit eens in 
longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 


negative. 


Condition Values Signaled 
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SS$_FLTOVF 


MTH$_FLOOVEMAT 
MTH$_FLOUNDMAT 
MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponentiation. This error is signaled 
if D-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if the 
D-floating-point-base is negative. 


OTS$POWGG 


OTS$POWGG—Raise a G-Floating Base to a G-Floating Exponent 


Format 


Returns 


Arguments 


Description 


The Raise a G-Floating Base to a G-Floating Exponent routine raises a G-floating 
base to a G-floating exponent. 


OTS$POWGG_ G-floating-point-base ,G-floating-point-exponent 


OpenVMS usage _ floating_point 


type G_floating 
access write only 
mechanism by value 


G-floating-point-base 
OpenVMS usage _ floating_point 


type G_floating 
access read only 
mechanism by value 


Base that OTS$POWGG raises to a G-floating exponent. The G-floating-point- 
base argument is a G-floating number containing the base. 


G-floating-point-exponent 
OpenVMS usage _ floating_point 


type G_floating 
access read only 
mechanism by value 


Exponent to which OTS$POWGG raises the base. The G-floating-point- 
exponent argument is a G-floating number containing the exponent. 


OTS$POWGG raises a G-floating base to a G-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The G-floating result for OTS$POWGG is as follows: 


Base Exponent Result 

= 0 >0 0.0 

= 0 = 0 Undefined exponentiation 
= 0 <0 Undefined exponentiation 
<0 Any Undefined exponentiation 
> 0 >0 olexponent+log2(base)] 

>0 = 0 1.0 
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Base Exponent 


> 0 <0 


olexponent«log2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 


SS$_FLTOVF 


MTH$_FLOOVEMAT 
MTH$_FLOUNDMAT 
MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponent. This error is signaled if 
G-floating-point-base is zero and G-floating- 


point-exponent is zero or negative, or if G- 
floating-point-base is negative. 


The arguments of OTSSPOWGG are passed by value. FORTRAN can 
only pass INTEGER and REAL*4 expressions as VALUE. Since 
INTEGER and REAL*4 values are one longword long, while REAL*8 
values are two longwords long, equate the base (and power) to 
two-dimensional INTEGER vectors. These vectors will be passed 


(M(1),Y) 


C To pass X by value, pass N(1) and N(2) by value. Similarly for Y. 


RESULT = OTSSPOWGG(%VAL(N(1)),SVAL(N(2)),SVAL(M(1)),SVAL(M(2)) ) 


Example 
C+ 
C This example demonstrates the use of OTSSPOWGG, 
C which raises a G-floating point base 
C toa G-floating point power. 
C- 
REAL*8 X,Y,RESULT, OTSSPOWGG 
C+ 
C 
3 
C 
C 
C 
C by VALUE. 
C- 
INTEGER N(2),M(2) 
EQUIVALENCE (N(1),X), 
X= 78:0 
Ye 20) 
C+ 
C- 
TYPE *,. 8.0%%2.0: 1S. ; RESULT 
X = 9.0 
Y= -0;5 
C+ 


In FORTRAN, OTSSPOWWGG is indirectly called by simply using the 


RESULT = A**Y 


C 
C exponentiation operator. 
C 


TYPE, 96 0"*=0..5 26°) oRESULE 


END 


This FORTRAN example uses OTS$POWGG to raise a G-floating base to a 


G-floating exponent. 
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The output generated by this example is as follows: 


3, 0** 2.018 64.0000000000000 
Oe 0FF20 75 WS. 0435353959999 5959 
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OTS$POWGJ—Raise a G-Floating Base to a Longword Exponent 


Format 


Returns 


Arguments 


Description 
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The Raise a G-Floating Base to a Longword Exponent routine raises a G-floating 
base to a longword exponent. 


OTS$POWGJ_ G-floating-point-base ,longword-integer-exponent 


OpenVMS usage _ floating_point 


type G_floating 
access write only 
mechanism by value 


G-floating-point-base 
OpenVMS usage  floating_point 


type G_floating 
access read only 
mechanism by value 


Base that OTS$POWGJ raises to a longword exponent. The G-floating-point- 
base argument is a G-floating number containing the base. 


longword-integer-exponent 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Exponent to which OTS$POWGJ raises the base. The longword-integer- 
exponent argument is a signed longword containing the exponent. 


OTS$POWGJ raises a G-floating base to a longword exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The floating-point result is as follows: 


Base Exponent Result 

Any >0 Product of (base**2') where i is each nonzero bit 
position in longword-integer-exponent 

>0 =0 1.0 

= =() Undefined exponentiation 

<0 = 0 1.0 

>0 <0 1.0/ (base**2'), where i is each nonzero bit position in 


longword-integer-exponent 
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Base Exponent Result 
= 0 <0 Undefined exponentiation 
<0 <0 1.0/ (base**2') where i is each nonzero bit position in 


longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 


Condition Values Signaled 


SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
MTH$_FLOOVEMAT Floating-point overflow in math library. 
MTH$_FLOUNDMAT Floating-point underflow in math library. 
MTH$_ UNDEXP Undefined exponent. This error is signaled if 


G-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if 
G-floating-point-base is negative. 
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OTS$POWHH_R3—Raise an H-Floating Base to an H-Floating 


<i> 


Format 


Returns 


Arguments 


Description 
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Exponent (VAX VMS Only) 


On an OpenVMS for VAX system, the Raise an H-Floating Base to an H-Floating 
}E}xponent routine raises an H-floating base to an H-floating exponent. 


OTS$POWHH_R3_ _H-floating-point-base ,H-floating-point-exponent 


OpenVMS usage  floating_point 


type H_floating 
access write only 
mechanism by value 


H-floating-point-base 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by value 


Base. The H-floating-point-base argument is an H-floating number containing 
the base. 


H-floating-point-exponent 
OpenVMS usage floating_point 


type H_floating 
access read only 
mechanism by value 


Exponent. The H-floating-point-exponent argument is an H-floating number 
that contains the H-floating exponent. 


OTS$POWHH_R3 raises an H-floating base to an H-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The H-floating result for OTS$POWHH_R3 is as follows: 


Base Exponent Result 

=0 > 0 00 — 

= 0 = 0 Undefined exponentiation 
= 0 <0 | Undefined exponentiation 
<0 Any Undefined exponentiation 
> 0 >0 plexponent+log2(base)] 


OTSSPOWHH_R3 


Base Exponent Result 
> 0 = 0 1.0 
>0 <0 olexponent+log2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 


Example 


SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

MTH$ FLOOVEMAT Floating-point overflow in math library. 

MTH$_FLOUNDMAT - Floating-point underflow in math library. 

MTH$ UNDEXP Undefined exponentiation. This error is signaled 


if H-floating-point-base is zero and H-floating- 
point-exponent is zero or negative, or if the 
H-floating-point-base is negative. 


C+ 

C Example of OTSSPOWHH, which raises an H_floating 

C point base to an H_floating point power. In FORTRAN, 
C it is not directly called. 


C- 
REAL*16 X,Y,RESULT 
X= 967 7356535.0 
Y = -0.5837653 

C+ 


C In FORTRAN, OTSSPOWWHH is indirectly called by simply using the 
C exponentiation operator. 
C- 
RESULT = ey 
TYPE *,% 987735653520**-0.5637653:..09.?4 RESULT 
END 
This FORTRAN example demonstrates how to call OTS$POWHH_R3 to raise an 
H-floating base to an H-floating power. 


The output generated by this program is as follows: 
9877356535.0**-0.5837653 IS 1.463779145994628357482343598205427E-00064 
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OTS$POWHJ_R3—Raise an H-Floating Base to a Longword 


<i> 


Format 


Returns 


Arguments 


Description 
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Exponent (VAX VMS Only) 


On an OpenVMS for VAX system, the Raise an H-Floating Base to a Longword 
Exponent routine raises an H-floating base to a longword exponent. 


OTS$POWHJ_R3_ _H-floating-point-base ,longword-integer-exponent 


OpenVMS usage floating_point 


type H_floating 
access write only 
mechanism by value 


H-floating-point-base 
OpenVMS usage floating_point 


type H_floating 
access read only 
mechanism by value 


Base. The H-floating-point-base argument is an H-floating number containing 
the base. 


longword-integer-exponent 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Exponent. The longword-integer-exponent argument is a signed longword 
that contains the signed longword exponent. 


OTS$POWHJ_R3 raises an H-floating base to a longword exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The floating-point result is as follows: 


Base Exponent Result 

Any >0 Product of (base**2') where i is each nonzero bit 
position in longword-integer-exponent 

>0 = 0 1.0 

= =0 Undefined exponentiation 

<0 = 0 1.0 


OTSS$POWHJ_R3 


Base Exponent Result 

>0 <0 1.0/ (base**2!), where i is each nonzero bit position in 
longword-integer-exponent 

= 0 <0 Undefined exponentiation 

<0 <0 1.0/ (base**2") where i is each nonzero bit position in 


longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 


Condition Values Signaled 


SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

MTH$_FLOOVEMAT Floating-point overflow in math library. 

MTH$_ FLOUNDMAT Floating-point underflow in math library. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if H-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if the 
H-floating-point-base is negative. ¢ 
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OTS$POWII—Raise a Word Base to a Word Exponent 


The Raise a Word Base to a Word Exponent routine raises a word base to a word 


exponent. 
Format 

OTS$POWII word-integer-base ,word-integer-exponent 
Returns 

OpenVMS usage word_signed 

type word (signed) 

access write only 

mechanism by value 
Arguments 


word-integer-base 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Base. The word-integer-base argument is a signed word containing the base. 


word-integer-exponent 
OpenVMS usage word_signed 


type word (signed) 
access read only 
mechanism by value 


Exponent. The word-integer-exponent argument is a signed word containing 
the exponent. 


Condition Values Signaled 


SS$_FLTDIV Arithmetic trap. This error is signaled by the 
hardware if a floating-point division by zero 
occurs. 

SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if word-integer-base is zero and word- 
integer-exponent is zero or negative, or if 
word-integer-base is negative. 
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OTS$POWJJ—Raise a Longword Base to a Longword Exponent 


Format 


Returns 


Arguments 


The Raise a Longword Base to a Longword Exponent routine raises a signed 
longword base to a signed longword exponent. 


OTS$POWJJ longword-integer-base ,longword-integer-exponent 


OpenVMS usage longword_signed 


type longword (signed) 
access write only 
mechanism by value 


longword-integer-base 
OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Base. The longword-integer-base argument is a signed longword containing 
the base. 


longword-integer-exponent 
OpenVMS usage _ longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Exponent. The longword-integer-exponent argument is a signed longword 
containing the exponent. 


Condition Values Signaled 


SS$_FLTDIV Arithmetic trap. This error is signaled by the 
hardware if a floating-point division by zero 
| occurs. 
SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
MTH$_UNDEXP Undefined exponentiation. This error is 


signaled if longword-integer-base is zero 
and longword-integer-exponent is zero 
or negative, or if longword-integer-base is 
negative. 
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OTS$POWLULU—Raise an Unsigned Longword Base to an Unsigned 


Format 


Returns 


Arguments 


Description 


Longword Exponent 


The Raise an Unsigned Longword Base to an Unsigned Longword Exponent 
routine raises an unsigned longword integer base to an unsigned longword 
integer exponent. — 


OTS$POWLULU _ unsigned-Iword-int-base, unsigned-Iword-int-exponent 


OpenVMS usage longword_unsigned 


type longword (unsigned) 
access write only 
mechanism by value 


unsigned-Iword-int-base 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
mechanism by value 


Unsigned longword integer base. The unsigned-lword-int-base argument 
contains the value of the integer base. 


unsigned-lword-int-exponent 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
mechanism by value 


Unsigned longword integer exponent. The unsigned-lword-int-exponent 
argument contains the value of the integer exponent. 


OTS$POWLULU returns the unsigned longword integer result of raising an 
unsigned longword integer base to an unsigned longword integer exponent. Note 
that overflow cannot occur in this routine. If the result or intermediate result is 
greater than 32 bits, the low-order 32 bits are used. 


Condition Values Signaled 
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MTH$ UNDEXP | Both the base and exponent values are zero. 


OTS$POWXxLU 


OTS$POWxLU—Raise a Floating-Point Base to an Unsigned 


Format 


<i> 


Returns 





<i> 


Arguments 


Longword Integer Exponent 


The Raise a Floating-Point Base to an Unsigned Longword Integer Exponent 
routines raises a floating-point base to an unsigned longword integer exponent. 


OTS$POWRLU _floating-point-base ,unsigned-lword-int-exponent 
OTS$POWDLU _floating-point-base ,unsigned-lword-int-exponent 
OTS$POWGLU | floating-point-base ,unsigned-lword-int-exponent 


OTS$POWHLU_R3 _ floating-point-base ,unsigned-Iword-int-exponent ¢ 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating, H_floating 
access write only 
mechanism by value 


Result of raising a floating-point base to an unsigned longword integer exponent. 
OTS$POWRLU returns an F-floating number. OTS$POWDLWU returns a D- 
floating number. OTS$POWGLU returns a G-floating number. 


OTS$POWHLU_R3 returns an H-floating number. ¢ 


floating-point-base 
OpenVMS usage  floating_point 


type F_floating, D_floating, G_floating, H_floating 
access read only 
mechanism by value 


Floating-point base. The floating-point-base argument contains the value 
of the base. For OTS$POWRLU, floating-point-base is an F-floating 
number. For OTS$POWDLU, floating-point-base is a D-floating number. 
For OTS$POWGLU, floating-point-base is a G-floating number. For 
OTS$POWHLU_R3, floating-point-base is an H-floating number. 


unsigned-lword-int-exponent 
OpenVMS usage longword_unsigned 


type longword (unsigned) 
access read only 
mechanism by value 


Integer exponent. The unsigned-Iword-int-exponent argument contains the 
value of the unsigned longword integer exponent. 
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Description 


OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and OTS$POWHLU_RS return 
the result of raising a floating-point base to an unsigned longword integer 
exponent. The floating-point result is as follows: 


Base Exponent Result 

Any >0 Product of (base*2') where i is each nonzero bit position 
in longword-integer-exponent 

>0 = 0 1.0 

= = Undefined exponentiation 

<0 = 1.0 


Condition Values Signaled 


MTH$_FLOOVEMAT Floating-point overflow in math library 


MTH$_FLOUNDMAT © Floating-point underflow in math library. This 
can only occur if the caller has floating-point 
underflow enabled. 

MTH$ UNDEXP Undefined exponentiation. This occurs if both the 
floating-point-base and unsigned-longword- 
integer-exponent arguments are zero. 
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OTS$POWRD—Raise an F-Floating Base to a D-Floating Exponent 


Format 


Returns 


Arguments 


Description 


The Raise an F-Floating Base to a D-Floating Exponent routine raises an F- 
floating base to a D-floating exponent. 


OTS$POWRD  F-floating-point-base ,D-floating-point-exponent 


OpenVMS usage  floating_point 


type D_floating 
access write only 
mechanism by value 


F-floating-point-base 
OpenVMS usage _ floating_point 


type F_ floating 
access read only 
mechanism by value 


Base. The F-floating-point-base argument is an F-floating number containing 
the base. 


D-floating-point-exponent 
OpenVMS usage  floating_point 


type D_floating 
access read only 
mechanism by value 


Exponent. The D-floating-point-exponent argument is a D-floating number 
that contains the exponent. 


OTS$POWRD raises an F-floating base to a D-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


OTS$POWRD first converts the F-floating base to D-floating. The D-floating 
result for OTS$POWRD is as follows: 


Base Exponent Result 

= 0 > 0 0.0 

= 0 =) Undefined exponentiation 
= 0 <0 Undefined exponentiation 
<0 Any Undefined exponentiation 
>0 >0 olexponentxLOG2(base)] 

>0 = 0 1.0 
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Base Exponent Result 


> 0 <0 olexponentx LOG2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 


Example 
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SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

MTH$_FLOOVEMAT - Floating-point overflow in math library. 

MTH$_ FLOUNDMAT Floating-point underflow in math library. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if F-floating-point-base is zero and D-floating- 
point-exponent is zero or negative, or if F- 
floating-point-base is negative. 


C+ 
C This FORTRAN example demonstrates the use 
C of OTSSPOWRD, which raises an F-floating point 
C base to a D-floating point exponent. The result is a 
C D-floating value. 
C- 
REAL*4 X 
REAL*8 Y,RESULT, OTSSPOWRD 
INTEGER M(2) 
EQUIVALENCE (M(1),Y) 
X= 9768.0 
Y = 9.0 
C+ 
C The arguments of OTSSPOWRD are passed by value. 
C- 
RESULT = OTSSPOWRD(%VAL(X), 3VAL(M(1)), SVAL(M(2) )) 
TYPE * 2" -9768.0** 90-15? : RESULT 
X = 7689.0 
Y = -0.587436654545 
C+ 


C In FORTRAN, OTSSPOWRD is indirectly called by simply 
C using the exponentiation operator. 


RESULT = X**Y 
TYPE *,’ 7689.0**-0.587436654545 IS ‘',RESULT 
END 


This FORTRAN example uses OTS$POWRD to raise an F-floating base to a 
D-floating exponent. Notice the difference in the precision of the result produced 
by this routine in comparison to the result produced by OTS$POWRR. 


OTS$POWRD 


The output generated by this program is as follows: 


9768.0**9.0 IS 8.0956338648832908E+35 
7689 .0**-0.587436654545 IS  5.2155199252836588E-03 
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OTS$POWRJ—Raise an F-Floating Base to a Longword Exponent 


Format 


Returns 


Arguments 


Description 
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The Raise an F-Floating Base to a Longword Exponent routine raises an F- 
floating base to a longword exponent. 


OTS$POWRJ  F-floating-point-base ,longword-integer-exponent 


OpenVMS usage _ floating_point 


type F floating 
access write only 
mechanism by value 


F-floating-point-base 
OpenVMS usage _floating_point 


type F floating 
access read only 
mechanism by value 


Base. The F-floating-point-base argument is an F-floating number containing 
the base. 


longword-integer-exponent 


OpenVMS usage longword_signed 


type longword (signed) 
access read only 
mechanism by value 


Exponent. The longword-integer-exponent argument is a signed longword 
that contains the longword exponent. 


OTS$POWRJ raises an F-floating base to a longword exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The floating-point result is as follows: 


Base _ Exponent Result 

Any >0 Product of (base**2') where i is each nonzero bit 
position in longword-integer-exponent 

>0 = 0 1.0 

= 0 = Undefined exponentiation 

<0 = 0 1.0 

>0 <0 1.0/ (base**2!), where i is each nonzero bit position in 


longword-integer-exponent 


OTS$POWRJ 


Base Exponent Result 
= 0 <0 Undefined exponentiation 
<0 <0 1.0/ (base**2") where i is each nonzero bit position in 


longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 


Condition Values Signaled 


SS$_FLTOVF Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

MTH$_ FLOOVEMAT Floating-point overflow in math library. 

MTH$ FLOUNDMAT Floating-point underflow in math library. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if F-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if 
F-floating-point-base is negative. 
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OTS$POWRR—Raise an F-Floating Base to an F-Floating Exponent 


Format 


Returns 


Arguments 


The Raise an F-Floating Base to an F-Floating Exponent routine raises an 
F-floating base to an F-floating exponent. 


OTS$POWRR_ F-floating-point-base ,F-floating-point-exponent 


OpenVMS usage _ floating_point 


type F_ floating 
access write only 
mechanism by value 


F-floating-point-base 
OpenVMS usage  floating_point 


type F_floating 
access read only 
mechanism by value 


Base. The F-floating-point-base argument is an F-floating number containing 
the base. 


F-floating-point-exponent 


~ OpenVMS usage  floating_point 


Description 
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type F_floating 
access read only 
mechanism by value 


Exponent. The F-floating-point-exponent argument is an F-floating number 
that contains the exponent. 


OTS$POWRR raises an F-floating base to an F-floating exponent. 


The internal calculations and the floating-point result have the same precision as 
the base value. 


The F-floating result for OTS$POWRR is as follows: 


Base Exponent Result 

= 0 >0 0.0 

= 0 = 0 Undefined exponentiation 
= 0 <0 Undefined exponentiation 
<0 Any Undefined exponentiation 
>0 >0 | plexponent+log2(base)] 

>0 = 0 1.0 


OTS$POWRR 


Base Exponent Result 


> 0 <0 glexponent+log2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. | 


_ Condition Values Signaled 


Example 


SS$_FLTOVF Arithmetic trap. This error is signaled by the 

| hardware if a floating-point overflow occurs. 
MTH$_FLOOVEMAT Floating-point overflow in math library. 
MTH$_FLOUNDMAT Floating-point underflow in math library. 
MTH$_UNDEXP Undefined exponentiation. This error is signaled 


if F-floating-point-base is zero and F-floating- 
point-exponent is zero or negative, or if F- 
floating-point-base is negative. 


C+ 
C This FORTRAN example demonstrates the use 
C of OTSSPOWRR, which raises an F-floating 
C point base to an F-floating point power. 
C- 
REAL*4 X,Y,RESULT, OTSSPOWRR 
X = 8.0 
YS 220 
C+ 
C The arguments of OTSSPOWRR are passed by value. 
C- 
RESULT = OTSSPOWRR(%VAL(X), $VAL(Y) ) 
TYPE: *;" @20**2.0- 18-*%; RESULT 
L-= O0 
Y= -0.5 
C+ 


C In FORTRAN, OTSSPOWRR is indirectly called by simply 
C using the exponentiation operator. 


RESULT = X**Y 
TYPE yp? D0" =0.5 15°“, RESULT 
END 


This FORTRAN example uses OTS$POWRR to raise an F-floating point base to 
an F-floating point exponent. The output generated by this program is as follows: 


G20**2.0' TS 64.00000 
B00 0:28. 0.393333 
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OTS$SCOPY_DXDX 


OTS$SCOPY_DXDX—Copy a Source String Passed by Descriptor to 


Format 


a Destination String 


The Copy a Source String Passed by Descriptor to a Destination String routine 
copies a source string to a destination string. Both strings are passed by 
descriptor. 


OTS$SCOPY_DXDX_ source-string ,destination-string 


corresponding jsb entry point 


Returns 


Arguments 
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OTS$SCOPY_DXDX6 


OpenVMS usage word_unsigned 


type word (unsigned) 
access write only 
mechanism by value 


If source-string contains more characters than destination-string, and the 
JSB entry point is used, RO contains the number of characters that were not 
copied. 


source-string 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by descriptor 


Source string. The source-string argument is the address of a descriptor 
pointing to the source string. The descriptor class can be unspecified, fixed 
length, dynamic, scalar decimal, array, noncontiguous array, or varying. 


destination-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor 


Destination string. The destination-string argument is the address of a 
descriptor pointing to the destination string. The class field determines the 
appropriate action. 


See the Description section for further information. 


Description 


OTS$SCOPY_DXDX 


OTS$SCOPY_DXDxX copies a source string to a destination string. All error 
conditions except truncation are signaled; truncation is ignored. 


OTS$SCOPY_DXDxX passes the source string by descriptor. In addition, an 
equivalent JSB entry point is provided, with RO being the first argument 
(the descriptor of the source string), and R1 the second (the descriptor of the 
destination string). 


For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, RO:R5 and the PSL are as they would be 
after a MOVC5 instruction. RO:R5 contain the following: 

RO Number of bytes of source string not moved to destination string 

Rl Address one byte beyond the last copied byte in the source string 

R2 0 

R3 Address one byte beyond the destination string 

R4 0 

R5 0 


For further information, see the VAX Architecture Reference Manual. 


Depending on the class of the destination string, the actions described below 
occur: 


Class Field Action 

DSC$K_CLASS_S,Z,SD,A,NCA Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D If the area specified by the destination 


descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 

DSC$K_CLASS_VS Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Adjust current length field to 
actual number of bytes copied. 


Condition Values Signaled 


OTS$_FATINTERR Fatal internal error. 
OTS$_INVSTRDES Invalid string descriptor. 
OTS$_INSVIRMEM Insufficient virtual memory. 
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OTS$SCOPY_R_DX 


OTS$SCOPY_R_DX—Copy a Source String Passed by Reference toa 


Format 


Destination String 


The Copy a Source String Passed by Reference to a Destination String routine 


copies a source string passed by reference to a destination string. 


OTS$SCOPY_R_DX_ word-int-source-length-val ,source-string-address 
,destination-string 


corresponding jsb entry point 


Returns 


Arguments 
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OTS$SCOPY_R_DX6 


OpenVMS usage word_unsigned 


type word (unsigned) 
access write only 
mechanism by value 


If source-string-address contains more characters than destination-string, 
and the JSB entry point is used, RO contains the number of characters that were 
not copied. 


word-int-source-length-val 
OpenVMS usage word_unsigned 


type word (unsigned) 
access read only 
mechanism by value 


Length of the source string. The word-int-source-length-val argument is an 
unsigned word integer containing the length of the source string. 


source-string-address 
OpenVMS usage _ char_string 


type character string 
access read only 
mechanism by reference 


Source string. The source-string-address argument is the address of the source 
string. 


destination-string 
OpenVMS usage _ char_string 


type character string 
access write only 
mechanism by descriptor 


Destination string. The destination-string argument is the address of a 
descriptor pointing to the destination string. The class field determines the 
appropriate action. The length field (DSC$W_LENGTH) alone or both the 


Description 


OTS$SCOPY_R_DX 


address (DSC$A_POINTER) and length fields can be modified if the string is 
dynamic. For varying strings, the current length is rewritten. 


OTS$SCOPY_R_DX copies a source string to a destination string. All conditions 
except truncation are signaled; truncation is ignored. Input scalars are passed by 
value. 


OTS$SCOPY_R_DX passes the source string by reference preceded by a length 
argument. In addition, an equivalent JSB entry point is provided, with RO being 
the first argument, R1 the second, and R2 the third, if any. The length argument 
is passed in bits 15:0 of the appropriate register. 


For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, RO:R5 and the PSL are as they would be 
after a MOVC5 instruction. RO:R5 contain the following: 

RO Number of bytes of source string not moved to destination string 

R1 Address one byte beyond the last copied byte in the source string 

R2 0 

R3 Address one byte beyond the destination string 

R4 0 

R5 0 


For additional information, see the VAX Architecture Reference Manual. 


Depending on the class of the destination string, the actions described below 
occur: 


Class Field Action | 

DSC$K_CLASS_S,Z,SD,A,NCA Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D If the area specified by the destination 


descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 


DSC$K_CLASS_VS Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Adjust current length field to 
actual number of bytes copied. 
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OTS$SCOPY_R_DX 


Condition Values Signaled 


Example 
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OTS$ FATINTERR Fatal internal error. 


OTS$_INVSTRDES Invalid string descriptor. 
OTS$_INSVIRMEM Insufficient virtual memory. 


A FORTRAN example demonstrating dynamic string manipulation appears at the 
end of OTS$SGET1_DD. This example uses OTS$SCOPY_R_DX, OTS$SGET1_ 
DD, and OTS$SFREE1_DD. 


OTS$SFREE1_DD 


OTSSSFREE1_DD—Strings, Free One Dynamic 


The Free One Dynamic String routine returns one dynamic string area to free 
storage. 


Format 
OTS$SFREE1_DD dynamic-descriptor 


corresponding jsb entry point 
OTS$SFREE1_DD6 


Returns 
None. 
Arguments 
dynamic-descriptor 
OpenVMS usage quadword_unsigned 
type quadword (unsigned) 
access modify 
mechanism by reference 
Dynamic string descriptor. The dynamic-descriptor argument is the address of 
the dynamic string descriptor. The descriptor is assumed to be dynamic and its 
class field is not checked. | 
Description 


OTS$SFREE1_DD deallocates the described string space and flags the descriptor 
as describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0). 


Condition Value Signaled 


OTS$ FATINTERR Fatal internal error. 


Example 


A FORTRAN example demonstrating dynamic string manipulation appears at the 
end of OTS$SGET1_DD. This example uses OTS$SFREE1_DD, OTS$SGET1_DD, 
and OTS$SCOPY_R_DX. 


OTS-91 


OTSS$SFREEn_DD 


OTS$SFREEn_DD—Sitrings, Free n Dynamic 


The Free n Dynamic Strings routine takes as input a vector of one or more 
dynamic string areas and returns them to free storage. 


Format 
OTS$SFREEN_DD  descriptor-count-value ,first-descriptor 


corresponding jsb entry point 
OTS$SFREEN_DD6 


Returns 
None. 
Arguments 
descriptor-count-value 
OpenVMS usage longword_unsigned 
type longword (unsigned) 
access read only 
mechanism by value 
Number of adjacent descriptors to be flagged as having no allocated area (DSC$A_ 
POINTER = 0 and DSC$W_LENGTH = 0) and to have their allocated areas 
returned to free storage by OTS$SFREEN_DD. The descriptor-count-value 
argument is an unsigned longword containing this number. 
first-descriptor 
OpenVMS usage quadword_unsigned 
type quadword (unsigned) 
access modify 
mechanism by reference 
First string descriptor of an array of string descriptors. The first-descriptor 
argument is the address of the first string descriptor. The descriptors are 
assumed to be dynamic, and their class fields are not checked. 
Description 


OTS$SFREEN_DD6 deallocates the described string space and flags each 
descriptor as describing no string at all (DSC$A_POINTER = 0 and DSC$W_ 
LENGTH = 0). 


Condition Values Signaled 


OTS$_ FATINTERR Fatal internal error. 
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OTS$SGET1_DD 


OTS$SGET1_DD—Strings, Get One Dynamic 


Format 


The Get One Dynamic String routine allocates a specified number of bytes of 
dynamic virtual memory to a specified string descriptor. 


OTS$SGET1_DD word-integer-length-value ,dynamic-descriptor 


corresponding jsb entry point 


Returns 


Arguments 


Description 


OTS$SGET1_DD_R6 


None. 


word-integer-length-value 
OpenVMS usage word_unsigned 


type word (unsigned) 
access read only 
mechanism by value 


Number of bytes to be allocated. The word-integer-length-value argument 
contains the number of bytes. The amount of storage allocated is automatically 
rounded up. If the number of bytes is zero, a small number of bytes is allocated. 


dynamic-descriptor 
OpenVMS usage quadword_unsigned 


type quadword (unsigned) 
access modify 
mechanism by reference 


Dynamic string descriptor to which the area is to be allocated. The dyn-str 
argument is the address of the dynamic string descriptor. The class field is not 
checked but it is set to dynamic (DSC$B_CLASS = 2). The length field (DSC$W_ 
LENGTH) is set to word-integer-length-value and the address field (DSC$A_ 
POINTER) is set to the string area allocated (first byte beyond the header). 


OTS$SGET1_DD allocates a specified number of bytes of dynamic virtual memory 
to a specified string descriptor. This routine is identical to OTS$SCOPY_DXDX 
except that no source string is copied. You can write anything you want in the 
allocated area. 


If the specified string descriptor already has dynamic memory allocated to it, 
but the amount allocated is either greater than or less than word-integer- 
length-value, that space is deallocated before OTS$SGET1_DD allocates new 
space. 
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OTS$SGET1_DD 


Condition Values Signaled 


OTS$_ FATINTERR Fatal internal error. 
OTS$_INSVIRMEM Insufficient virtual memory. 


Example 


PROGRAM STRING_TEST 


C+ 
C This program demonstrates the use of some dynamic string 
C manipulation routines. 
C- 
C+ 
c DECLARATIONS 
C- 
IMPLICIT NONE 
CHARACTER* 80 DATA_LINE 
INTEGER* 4 DATA_LEN, DSC(2), CRLF_DSC(2), TEMP_DSC (2) 
CHARACTER*2 CRLF | 
C+ 
C Initialize the output descriptor. It should be empty. 
C- 
CALL OTSSSGET1_DD(%VAL(0), DSC) 
C+ | 
C Initialize a descriptor to the string CRLF and copy the 
C character CRLF to it. 
C- 
CALL OTSSSGET1_DD(%VAL(2), CRLF_DSC) 
CRLF = CHAR(13)//CHAR(10) 
CALL OTSSSCOPY_R_DX( %VAL(2), SREF(CRLF(1:1)), CRLF_DSC) 
C+ 
C Initialize a temporary descriptor. 
Ce 
| CALL OTSSSGET1_DD($VAL(0), TEMP_DSC) 
C+ 
C Prompt the user. 
C- 
WRITE (6, 999) 
999 FORMAT(1X, ‘Enter your message, end with Ctrl/Z.') 
C+ 
C Read lines of text from the terminal until end-of-file. 
C Concatenate each line to the previous input. Include a 
C CRLF between each line. 
C- 


DO WHILE (.TRUE.) 
READ(5, 998, ERR = 10) DATA_LEN, DATA_LINE 
998 FORMAT (Q, A) 
CALL OTSSSCOPY_R_DX( %VAL(DATA_LEN), 


iN SREF (DATA_LINE(1:1)), 
2 TEMP_DSC)}) | 
CALL STRSCONCAT( DSC, DSC, TEMP_DSC, CRLF_DSC )} 
END DO 
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C+ 


C- 


10 
C+ 


C- 


C+ 


C- 


OTS$SGET1_DD 


The user has typed Ctrl/Z. Output the data we read. 


CALL LIBSPUT_OUTPUT( DSC ) 


Free the storage allocated to the dynamic strings. 


CALL OTSSSFREE1_DD( DSC ) 
CALL OTSSSFREE1_DD( CRLF_DSC } 
CALL OTSSSFREE1_DD( TEMP_DSC ) 


End of program. 


STOP 
END 


This FORTRAN example program demonstrates dynamic string manipulation 
using OTS$SGET1_DD, OTS$SFREE1_DD, and OTS$SCOPY_R_DX. 
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How to Order Additional Documentation 





Technical Support 
If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) 
and press 2 for technical assistance. 


Electronic Orders 


If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a 
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits, no 
parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an 
Electronic Store specialist. | 


Telephone and Direct Mail Orders 


From 
U.S.A. 


Puerto Rico 


Canada 


International 


Internal Orders? 
(for software 
documentation) 


Internal Orders 
(for hardware 
documentation) 


Call 


DECdirect 

Phone: 800-DIGITAL 
(800-344-4825) 

FAX: (603) 884-5597 


Phone: (809) 781-0505 
FAX: (809) 749-8377 


Phone: 800-267-6215 
FAX: (613) 592-1946 


DTN: 241-3023 
(508) 874-3023 


DTN: 234-4325 
(508) 351-4325 
FAX: (508) 351-4467 


Write 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 
3 Digital Plaza, 1st Street 

Suite 200 

Metro Office Park 

San Juan, Puerto Rico 00920 


Digital Equipment of Canada Ltd. 
100 Herzberg Road 


Kanata, Ontario, Canada K2K 2A6 


Attn: DECdirect Sales 


Local Digital subsidiary or 
approved distributor 


Software Supply Business (SSB) 
Digital Equipment Corporation 
1 Digital Drive 

Westminster, MA 01473 


Publishing & Circulation Services 
Digital Equipment Corporation 
NRO0O2-2 

444 Whitney Street 

Northboro, MA 01532 


‘Call to request an Internal Software Order Form (EN-01740-07). 
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